@daniel.stefan/metalink 1.3.1

package/packages/core/dist/server/manager.js

@@ -0,0 +1,3255 @@
+/**
+ * Server Manager - Handles spawning and managing MCP server processes and HTTP clients
+ */
+import { spawn, spawnSync } from "child_process";
+import path from "path";
+import { EventEmitter } from "events";
+import { LRUCache } from "lru-cache";
+import { version } from "../index.js";
+import { ProcessManager, HttpConnectionManager, SchemaCacheManager, } from "./managers/index.js";
+import { SchemaStore } from "./schema-store.js";
+import { SchemaValidator } from "./schema-validator.js";
+import { globalMetrics } from "../metrics/index.js";
+import { CircuitBreakerManager } from "./circuit-breaker.js";
+export class ServerManager extends EventEmitter {
+    /**
+     * Constructor - Initialize with configurable schema cache TTL and persistent storage
+     */
+    constructor(config) {
+        super();
+        this.processes = new Map();
+        this.httpClients = new Map(); // Track HTTP clients
+        this.state = {};
+        this.healthCheckIntervals = new Map();
+        this.activeServers = new Map(); // Track server tools
+        this.baseServers = [];
+        this.baseServersEnabled = false;
+        this.schemasCacheTTL = 300000; // Default 5 minutes in ms
+        // Persistent schema storage
+        this.schemaStore = null;
+        this.schemasBackgroundRefresh = true;
+        this.backgroundRefreshInterval = null;
+        this.BACKGROUND_REFRESH_INTERVAL_MS = 60000; // 1 minute
+        // Adaptive TTL configuration
+        this.schemaStabilityMetrics = new Map();
+        this.ADAPTIVE_TTL_ENABLED = true;
+        this.TTL_STABLE = 3600000; // 60 minutes for stable schemas
+        this.TTL_NORMAL = 300000; // 5 minutes for normal schemas (default)
+        this.TTL_UNSTABLE = 300000; // 5 minutes for unstable schemas (same as normal)
+        this.STABILITY_WINDOW = 5; // Look at last 5 refreshes
+        this.UNSTABLE_THRESHOLD = 2; // Changed in last 2 refreshes = unstable
+        this.discoveredServers = new Set();
+        // Discovery TTL properties (v1.4.0)
+        this.discoveryTimers = new Map();
+        this.discoveryTTL = 600000; // 10 minutes (configurable)
+        // v1.3.74: Failed discovery tracking - skip servers that fail repeatedly
+        this.failedDiscoveryAttempts = new Map();
+        this.MAX_DISCOVERY_FAILURES = 3; // Skip after this many failures
+        this.DISCOVERY_FAILURE_BACKOFF_MS = 3600000; // 1 hour backoff
+        // v1.1.8: Startup Mutex - Prevents race condition in ensureServerStarted()
+        this.startupMutex = new Map();
+        // Auto-restart tracking for failed servers
+        this.autoRestartConfig = {
+            enabled: true,
+            maxRetries: 3,
+            baseDelay: 5000, // 5 seconds
+            maxDelay: 300000, // 5 minutes
+            backoffMultiplier: 2,
+        };
+        this.restartAttempts = new Map();
+        // Phase 3: Response router state
+        this.stdoutBuffers = new Map(); // Buffer per server
+        this.stdoutListeners = new Map(); // Listener references for cleanup
+        this.pendingRequests = new Map(); // Pending requests per server
+        // v1.1.49: Monotonic request ID counters per server (fixes ID collision bug)
+        this.requestIdCounters = new Map();
+        // Timeout configuration (in milliseconds)
+        this.timeouts = {
+            serverInit: 10000, // 10s - Server initialization timeout
+            toolFetch: 60000, // 60s - Tool fetch timeout
+            toolExecution: 300000, // 5min - Tool execution timeout
+            gracefulShutdown: 5000, // 5s - Graceful shutdown timeout
+        };
+        // Initialize circuit breaker manager with configuration
+        this.circuitBreakerManager = new CircuitBreakerManager({
+            failureThreshold: config?.circuitBreaker?.failureThreshold ?? 3,
+            resetTimeout: config?.circuitBreaker?.resetTimeout ?? 30000,
+            halfOpenSuccessThreshold: config?.circuitBreaker?.halfOpenSuccessThreshold ?? 1,
+            onStateChange: (oldState, newState, serverName) => {
+                console.log(`[CircuitBreaker] ${serverName}: ${oldState} → ${newState}`);
+                this.emit("circuit-breaker-state-change", {
+                    serverName,
+                    oldState,
+                    newState,
+                });
+            },
+        });
+        // Phase 1-3: Initialize extracted managers
+        this.processManager = new ProcessManager(this.circuitBreakerManager, {
+            autoRestart: this.autoRestartConfig,
+        });
+        this.httpConnectionManager = new HttpConnectionManager({
+            timeouts: {
+                gracefulShutdown: this.timeouts.gracefulShutdown,
+            },
+        });
+        this.schemaCacheManager = new SchemaCacheManager({
+            cacheTTL: config?.schemasCacheTTL ?? 300000,
+            maxCacheEntries: config?.maxSchemaCacheEntries ?? 100,
+            backgroundRefresh: config?.schemasBackgroundRefresh ?? true,
+            cacheDir: config?.schemasCachePath ?? "~/.config/metalink/schemas",
+        });
+        // Forward events from managers
+        this.processManager.on("server:started", ({ name, pid }) => {
+            this.emit("server:started", { name, pid });
+        });
+        this.processManager.on("server:stopped", ({ name }) => {
+            this.emit("server:stopped", { name });
+        });
+        this.processManager.on("health:check", (result) => {
+            this.emit("health:check", result);
+        });
+        this.httpConnectionManager.on("server:started", ({ name, type, url }) => {
+            this.emit("server:started", { name, type, url });
+        });
+        this.httpConnectionManager.on("server:stopped", ({ name }) => {
+            this.emit("server:stopped", { name });
+        });
+        this.httpConnectionManager.on("health:check", (result) => {
+            this.emit("health:check", result);
+        });
+        // Initialize auto-restart configuration
+        if (config?.autoRestart) {
+            if (config.autoRestart.enabled !== undefined) {
+                this.autoRestartConfig.enabled = config.autoRestart.enabled;
+            }
+            if (config.autoRestart.maxRetries !== undefined) {
+                this.autoRestartConfig.maxRetries = config.autoRestart.maxRetries;
+            }
+            if (config.autoRestart.baseDelay !== undefined) {
+                this.autoRestartConfig.baseDelay = config.autoRestart.baseDelay;
+            }
+            if (config.autoRestart.maxDelay !== undefined) {
+                this.autoRestartConfig.maxDelay = config.autoRestart.maxDelay;
+            }
+            if (config.autoRestart.backoffMultiplier !== undefined) {
+                this.autoRestartConfig.backoffMultiplier =
+                    config.autoRestart.backoffMultiplier;
+            }
+            console.log(`[ServerManager] Auto-restart configured:`, this.autoRestartConfig);
+        }
+        // Load base servers from config (empty array if not configured)
+        this.baseServers = config?.base_servers || [];
+        if (this.baseServers.length > 0) {
+            console.log(`[ServerManager] Base servers configured:`, this.baseServers);
+        }
+        if (config?.schemasCacheTTL) {
+            this.schemasCacheTTL = config.schemasCacheTTL;
+            console.log(`[ServerManager] Schema cache TTL configured to ${config.schemasCacheTTL}ms`);
+        }
+        // Initialize LRU cache for schemas with bounded memory
+        const maxCacheEntries = config?.maxSchemaCacheEntries ?? 100;
+        this.toolSchemaCache = new LRUCache({
+            max: maxCacheEntries,
+            dispose: (value, key) => {
+                console.log(`[ServerManager] LRU eviction: ${key} (${value.tools.length} tools, age: ${Date.now() - value.timestamp}ms)`);
+            },
+        });
+        console.log(`[ServerManager] Schema cache initialized with max ${maxCacheEntries} entries`);
+        // Initialize persistent schema store
+        const cachePath = config?.schemasCachePath || "~/.config/metalink/schemas";
+        // Expand ~ to home directory (v1.3.60: global cache across versions)
+        const expandedCachePath = cachePath.startsWith("~/")
+            ? cachePath.replace("~", process.env.HOME || process.env.USERPROFILE || "~")
+            : cachePath;
+        this.schemaStore = new SchemaStore(expandedCachePath, this.schemasCacheTTL);
+        // Load cached schemas from disk on startup
+        this.loadSchemasFromDisk();
+        // Initialize background refresh setting
+        if (config?.schemasBackgroundRefresh !== undefined) {
+            this.schemasBackgroundRefresh = config.schemasBackgroundRefresh;
+        }
+        // Initialize discovery TTL (v1.4.0)
+        if (config?.discoveryTTL !== undefined) {
+            this.discoveryTTL = config.discoveryTTL;
+            console.log(`[ServerManager] Discovery TTL configured to ${config.discoveryTTL}ms`);
+        }
+        else if (process.env.METALINK_DISCOVERY_TTL) {
+            this.discoveryTTL = parseInt(process.env.METALINK_DISCOVERY_TTL);
+            console.log(`[ServerManager] Discovery TTL from env: ${this.discoveryTTL}ms`);
+        }
+        // Initialize timeout configuration
+        if (config?.timeouts) {
+            if (config.timeouts.serverInit !== undefined) {
+                this.timeouts.serverInit = config.timeouts.serverInit;
+            }
+            if (config.timeouts.toolFetch !== undefined) {
+                this.timeouts.toolFetch = config.timeouts.toolFetch;
+            }
+            if (config.timeouts.toolExecution !== undefined) {
+                this.timeouts.toolExecution = config.timeouts.toolExecution;
+            }
+            if (config.timeouts.gracefulShutdown !== undefined) {
+                this.timeouts.gracefulShutdown = config.timeouts.gracefulShutdown;
+            }
+            console.log(`[ServerManager] Timeouts configured:`, this.timeouts);
+        }
+        // Override with environment variables if present
+        if (process.env.METALINK_TIMEOUT_INIT) {
+            this.timeouts.serverInit = parseInt(process.env.METALINK_TIMEOUT_INIT);
+            console.log(`[ServerManager] Server init timeout from env: ${this.timeouts.serverInit}ms`);
+        }
+        if (process.env.METALINK_TIMEOUT_TOOL_FETCH) {
+            this.timeouts.toolFetch = parseInt(process.env.METALINK_TIMEOUT_TOOL_FETCH);
+            console.log(`[ServerManager] Tool fetch timeout from env: ${this.timeouts.toolFetch}ms`);
+        }
+        if (process.env.METALINK_TIMEOUT_TOOL_EXECUTION) {
+            this.timeouts.toolExecution = parseInt(process.env.METALINK_TIMEOUT_TOOL_EXECUTION);
+            console.log(`[ServerManager] Tool execution timeout from env: ${this.timeouts.toolExecution}ms`);
+        }
+        if (process.env.METALINK_TIMEOUT_SHUTDOWN) {
+            this.timeouts.gracefulShutdown = parseInt(process.env.METALINK_TIMEOUT_SHUTDOWN);
+            console.log(`[ServerManager] Graceful shutdown timeout from env: ${this.timeouts.gracefulShutdown}ms`);
+        }
+        // Start background refresh if enabled
+        if (this.schemasBackgroundRefresh) {
+            this.startBackgroundRefresh();
+        }
+    }
+    /**
+     * Load cached schemas from disk into memory on startup
+     * Restores schemas across daemon restarts
+     */
+    async loadSchemasFromDisk() {
+        if (!this.schemaStore)
+            return;
+        try {
+            const diskSchemas = await this.schemaStore.loadFromDisk();
+            let loadedCount = 0;
+            for (const [serverName, schema] of diskSchemas) {
+                // Load all schemas from disk regardless of TTL (persist across restarts)
+                // Background refresh will update expired schemas for running servers
+                this.toolSchemaCache.set(serverName, schema);
+                this.schemaStore.updateMemoryCache(serverName, schema);
+                this.discoveredServers.add(serverName);
+                // Restore stability metrics from disk
+                if (schema.stability) {
+                    this.schemaStabilityMetrics.set(serverName, {
+                        serverName,
+                        refreshCount: schema.stability.refreshCount,
+                        changeCount: schema.stability.changeCount,
+                        lastChangeTimestamp: schema.stability.lastChangeTimestamp,
+                        currentTTL: schema.stability.currentTTL,
+                        stability: schema.stability.stability,
+                    });
+                }
+                loadedCount++;
+            }
+            console.log(`[SchemaStore] Loaded ${loadedCount} valid schemas from disk (with stability metrics)`);
+        }
+        catch (error) {
+            console.warn("[SchemaStore] Failed to load schemas from disk:", error);
+            // Continue without disk cache - will fetch on demand
+        }
+    }
+    /**
+     * Calculate adaptive TTL based on schema stability
+     * Returns TTL in milliseconds
+     */
+    calculateAdaptiveTTL(serverName) {
+        if (!this.ADAPTIVE_TTL_ENABLED) {
+            return this.schemasCacheTTL; // Use default if disabled
+        }
+        const metrics = this.schemaStabilityMetrics.get(serverName);
+        if (!metrics) {
+            return this.TTL_NORMAL; // Default for new servers
+        }
+        // Stable: 0 changes in last 5 refreshes → 60 minute TTL
+        if (metrics.refreshCount >= this.STABILITY_WINDOW &&
+            metrics.changeCount === 0) {
+            return this.TTL_STABLE;
+        }
+        // Unstable: changed in last 2 refreshes → 5 minute TTL (same as normal)
+        if (metrics.changeCount >= this.UNSTABLE_THRESHOLD) {
+            return this.TTL_UNSTABLE;
+        }
+        // Normal: between stable and unstable → 5 minute TTL
+        return this.TTL_NORMAL;
+    }
+    /**
+     * Classify stability level for logging
+     */
+    getStabilityLevel(serverName) {
+        const metrics = this.schemaStabilityMetrics.get(serverName);
+        if (!metrics)
+            return "normal";
+        if (metrics.refreshCount >= this.STABILITY_WINDOW &&
+            metrics.changeCount === 0) {
+            return "stable";
+        }
+        if (metrics.changeCount >= this.UNSTABLE_THRESHOLD) {
+            return "unstable";
+        }
+        return "normal";
+    }
+    /**
+     * Detect if schema has changed (compare tool names and counts)
+     */
+    hasSchemaChanged(oldTools, newTools) {
+        if (oldTools.length !== newTools.length) {
+            return true;
+        }
+        // Compare tool names (sorted)
+        const oldNames = oldTools.map((t) => t.name).sort();
+        const newNames = newTools.map((t) => t.name).sort();
+        for (let i = 0; i < oldNames.length; i++) {
+            if (oldNames[i] !== newNames[i]) {
+                return true;
+            }
+        }
+        return false; // No changes detected
+    }
+    /**
+     * Update stability metrics after refresh
+     */
+    updateStabilityMetrics(serverName, schemaChanged) {
+        let metrics = this.schemaStabilityMetrics.get(serverName);
+        if (!metrics) {
+            // Initialize new metrics
+            metrics = {
+                serverName,
+                refreshCount: 0,
+                changeCount: 0,
+                lastChangeTimestamp: 0,
+                currentTTL: this.TTL_NORMAL,
+                stability: "normal",
+            };
+            this.schemaStabilityMetrics.set(serverName, metrics);
+        }
+        // Update counters
+        metrics.refreshCount++;
+        if (schemaChanged) {
+            metrics.changeCount++;
+            metrics.lastChangeTimestamp = Date.now();
+            // Reset stability window when schema changes
+            // Only keep last STABILITY_WINDOW refreshes
+            if (metrics.refreshCount > this.STABILITY_WINDOW) {
+                metrics.refreshCount = this.STABILITY_WINDOW;
+                metrics.changeCount = Math.min(metrics.changeCount, this.UNSTABLE_THRESHOLD);
+            }
+        }
+        else {
+            // Schema stable - decay change count over time
+            if (metrics.refreshCount >= this.STABILITY_WINDOW) {
+                metrics.changeCount = Math.max(0, metrics.changeCount - 1);
+            }
+        }
+        // Recalculate TTL
+        metrics.currentTTL = this.calculateAdaptiveTTL(serverName);
+        metrics.stability = this.getStabilityLevel(serverName);
+    }
+    /**
+     * Start background refresh interval
+     * Periodically refreshes schemas for servers near TTL expiration
+     */
+    startBackgroundRefresh() {
+        if (this.backgroundRefreshInterval) {
+            return; // Already running
+        }
+        this.backgroundRefreshInterval = setInterval(async () => {
+            await this.refreshExpiredSchemas();
+            // v1.3.72: Also proactively discover schemas for uncached servers
+            await this.discoverUncachedServers();
+        }, this.BACKGROUND_REFRESH_INTERVAL_MS);
+        const adaptiveMsg = this.ADAPTIVE_TTL_ENABLED
+            ? ` (adaptive TTL: stable=${this.TTL_STABLE}ms, normal=${this.TTL_NORMAL}ms)`
+            : "";
+        console.log(`[SchemaStore] Background refresh enabled (interval: 1min, refresh at 80% TTL${adaptiveMsg})`);
+    }
+    /**
+     * Refresh schemas that are expiring soon (>80% of adaptive TTL)
+     * Only refreshes servers that are already running
+     */
+    async refreshExpiredSchemas() {
+        const now = Date.now();
+        for (const [serverName, schema] of this.toolSchemaCache) {
+            // Use adaptive TTL per server
+            const serverTTL = this.calculateAdaptiveTTL(serverName);
+            const expireThreshold = serverTTL * 0.8; // 80% of adaptive TTL
+            const age = now - schema.timestamp;
+            // Skip if not near expiration
+            if (age < expireThreshold) {
+                continue;
+            }
+            // Skip if server not running (no need to refresh)
+            if (!this.isServerActive(serverName)) {
+                continue;
+            }
+            try {
+                const oldTools = schema.tools;
+                const process = this.getProcess(serverName);
+                if (!process)
+                    continue;
+                const tools = await this.fetchToolsFromProcess(process, serverName);
+                // Detect schema change
+                const schemaChanged = this.hasSchemaChanged(oldTools, tools);
+                // Update stability metrics
+                this.updateStabilityMetrics(serverName, schemaChanged);
+                // Get updated metrics
+                const metrics = this.schemaStabilityMetrics.get(serverName);
+                // Log refresh with stability info
+                const changeMsg = schemaChanged ? " (schema changed)" : " (no changes)";
+                const stabilityMsg = metrics
+                    ? ` [${metrics.stability}, TTL: ${metrics.currentTTL}ms]`
+                    : "";
+                console.log(`[SchemaStore] Background refresh for ${serverName}${changeMsg}${stabilityMsg}`);
+                // Prepare new schema with stability metrics
+                const newSchema = {
+                    tools,
+                    timestamp: now,
+                    stability: metrics
+                        ? {
+                            refreshCount: metrics.refreshCount,
+                            changeCount: metrics.changeCount,
+                            lastChangeTimestamp: metrics.lastChangeTimestamp,
+                            currentTTL: metrics.currentTTL,
+                            stability: metrics.stability,
+                        }
+                        : undefined,
+                };
+                // Update memory cache
+                this.toolSchemaCache.set(serverName, { tools, timestamp: now });
+                // Persist to disk (non-blocking)
+                if (this.schemaStore) {
+                    this.schemaStore.saveToDisk(serverName, newSchema).catch((error) => {
+                        console.warn(`[SchemaStore] Failed to persist refreshed schema for ${serverName}:`, error);
+                    });
+                }
+            }
+            catch (error) {
+                console.warn(`[SchemaStore] Background refresh failed for ${serverName}:`, error);
+            }
+        }
+    }
+    /**
+     * v1.3.72: Proactively discover schemas for servers without cache
+     * Starts servers one at a time to avoid overload, fetches schemas, then stops them
+     * Only discovers ONE server per refresh cycle to avoid overwhelming the system
+     */
+    async discoverUncachedServers() {
+        if (!this.serverListProvider) {
+            return; // No provider set, can't discover
+        }
+        try {
+            const allServers = this.serverListProvider();
+            // Find first server without cached schema (disk or memory)
+            for (const config of allServers) {
+                const serverName = config.name;
+                // Skip if already has cached schema in memory
+                if (this.toolSchemaCache.has(serverName)) {
+                    continue;
+                }
+                // Skip if already has cached schema on disk
+                if (this.schemaStore) {
+                    const diskCached = this.schemaStore.getSyncFromDisk(serverName);
+                    if (diskCached && diskCached.length > 0) {
+                        // Also populate memory cache
+                        this.toolSchemaCache.set(serverName, {
+                            tools: diskCached,
+                            timestamp: Date.now(),
+                        });
+                        continue;
+                    }
+                }
+                // Skip if already running (will be discovered via normal flow)
+                if (this.isServerActive(serverName)) {
+                    continue;
+                }
+                // v1.3.74: Skip if server has failed too many times recently
+                const failedAttempt = this.failedDiscoveryAttempts.get(serverName);
+                if (failedAttempt) {
+                    const timeSinceLastAttempt = Date.now() - failedAttempt.lastAttempt;
+                    if (failedAttempt.count >= this.MAX_DISCOVERY_FAILURES &&
+                        timeSinceLastAttempt < this.DISCOVERY_FAILURE_BACKOFF_MS) {
+                        // Skip this server, still in backoff period
+                        continue;
+                    }
+                    // Reset if backoff period has passed
+                    if (timeSinceLastAttempt >= this.DISCOVERY_FAILURE_BACKOFF_MS) {
+                        this.failedDiscoveryAttempts.delete(serverName);
+                        console.log(`[SchemaStore] Proactive discovery: ${serverName} backoff expired, will retry`);
+                    }
+                }
+                // Discover this server's schema
+                console.log(`[SchemaStore] Proactive discovery: starting ${serverName} to fetch schemas...`);
+                try {
+                    // Start server
+                    await this.startServer(config);
+                    let tools = [];
+                    // Check if HTTP or stdio server
+                    const isHttpServer = this.httpClients.has(serverName);
+                    if (isHttpServer) {
+                        const client = this.httpClients.get(serverName);
+                        const response = await client.call("tools/list", {});
+                        if (response.result &&
+                            typeof response.result === "object" &&
+                            "tools" in response.result) {
+                            tools = response.result.tools;
+                        }
+                    }
+                    else {
+                        const process = this.getProcess(serverName);
+                        if (process) {
+                            tools = await this.fetchToolsFromProcess(process, serverName);
+                        }
+                    }
+                    // Cache the schema
+                    const schema = { tools, timestamp: Date.now() };
+                    this.toolSchemaCache.set(serverName, schema);
+                    // Persist to disk
+                    if (this.schemaStore) {
+                        await this.schemaStore.saveToDisk(serverName, schema);
+                    }
+                    console.log(`[SchemaStore] Proactive discovery: ${serverName} cached (${tools.length} tools)`);
+                    // v1.1.33: Don't kill servers after caching - let them stay running
+                    // This prevents "process has been killed" errors and improves latency
+                    // await this.stopServer(serverName);
+                    // console.log(`[SchemaStore] Proactive discovery: ${serverName} stopped after caching`);
+                    // Only discover ONE server per cycle to avoid overwhelming the system
+                    return;
+                }
+                catch (error) {
+                    console.warn(`[SchemaStore] Proactive discovery failed for ${serverName}:`, error);
+                    // v1.3.74: Track failure for backoff
+                    const existing = this.failedDiscoveryAttempts.get(serverName);
+                    const failureCount = (existing?.count || 0) + 1;
+                    this.failedDiscoveryAttempts.set(serverName, {
+                        count: failureCount,
+                        lastAttempt: Date.now(),
+                    });
+                    if (failureCount >= this.MAX_DISCOVERY_FAILURES) {
+                        console.log(`[SchemaStore] Proactive discovery: ${serverName} failed ${failureCount} times, skipping for 1 hour`);
+                    }
+                    // Try to stop if it was started
+                    try {
+                        await this.stopServer(serverName);
+                    }
+                    catch {
+                        // Ignore stop errors
+                    }
+                    // Continue to next server in next cycle
+                    return;
+                }
+            }
+        }
+        catch (error) {
+            console.warn("[SchemaStore] Proactive discovery error:", error);
+        }
+    }
+    /**
+     * Start a server process (stdio or HTTP)
+     */
+    async startServer(config) {
+        if (this.processes.has(config.name) || this.httpClients.has(config.name)) {
+            throw new Error(`Server ${config.name} is already running`);
+        }
+        // Route to appropriate handler based on transport
+        if (config.transport === "stdio" || config.transport === undefined) {
+            return this.startStdioServer(config);
+        }
+        else {
+            return this.startHttpServer(config);
+        }
+    }
+    /**
+     * Start a stdio-based server (spawns process)
+     */
+    async startStdioServer(config) {
+        try {
+            // Helper to expand env var syntax: ${VAR} and ~/path
+            const expandEnvVar = (value, env) => {
+                // Expand ${VAR_NAME} syntax
+                let expanded = value.replace(/\$\{([^}]+)\}/g, (_, key) => env[key] || value);
+                // Expand ~ to home directory
+                if (expanded.startsWith("~")) {
+                    expanded = expanded.replace(/^~/, env.HOME || "/root");
+                }
+                return expanded;
+            };
+            // Replace environment variables in args and env values
+            const processEnv = {
+                ...process.env,
+            };
+            // Expand and add config.env
+            if (config.env) {
+                for (const [key, value] of Object.entries(config.env)) {
+                    processEnv[key] = expandEnvVar(value, processEnv);
+                }
+            }
+            // Resolve env vars in args
+            const args = (config.args || []).map((arg) => expandEnvVar(arg, processEnv));
+            // Prepare spawn options with optional cwd
+            const spawnOptions = {
+                env: processEnv,
+                stdio: "pipe",
+            };
+            // Add cwd if configured
+            if (config.cwd) {
+                // Expand ~ and env variables in cwd path
+                let cwdPath = config.cwd;
+                if (cwdPath.startsWith("~")) {
+                    cwdPath = cwdPath.replace(/^~/, processEnv.HOME || "/root");
+                }
+                // Resolve to absolute path
+                spawnOptions.cwd = path.resolve(cwdPath);
+                console.log(`[${config.name}] Starting with cwd: ${spawnOptions.cwd}`);
+            }
+            // v1.1.52: Robust orphan process cleanup with security fixes
+            // Addresses: command injection, false positives, cross-user matching, parent process exclusion
+            // Step 1: Kill any in-memory tracked process (from this ServerManager instance)
+            const existingProcess = this.processes.get(config.name);
+            if (existingProcess && !existingProcess.killed) {
+                console.log(`[${config.name}] Killing tracked orphan process (PID: ${existingProcess.pid}) before starting new instance`);
+                try {
+                    existingProcess.kill("SIGTERM");
+                    await new Promise((resolve) => setTimeout(resolve, 300));
+                    if (!existingProcess.killed) {
+                        existingProcess.kill("SIGKILL");
+                    }
+                }
+                catch (killError) {
+                    console.warn(`[${config.name}] Failed to kill tracked process:`, killError);
+                }
+                this.processes.delete(config.name);
+                this.activeServers.delete(config.name);
+            }
+            // Step 2: Kill system orphan processes using METALINK_SERVER_NAME env var
+            // This is the unique identifier we inject into spawned processes
+            const serverNamePattern = `METALINK_SERVER_NAME=${config.name}`;
+            // Also create fallback pattern from args (for processes from older versions)
+            // Use scoped package names (@org/pkg) which are unique, avoid generic patterns
+            const packageIdentifier = args.find((arg) => arg.includes("@") && arg.includes("/")) ||
+                (config.command !== "npx" && config.command !== "uvx"
+                    ? config.command
+                    : null);
+            // Get PIDs to exclude: current process + parent + grandparent
+            const excludePids = new Set();
+            excludePids.add(String(process.pid));
+            try {
+                const ppidResult = spawnSync("ps", ["-o", "ppid=", "-p", String(process.pid)], { encoding: "utf8", timeout: 2000 });
+                const ppid = ppidResult.stdout?.trim();
+                if (ppid) {
+                    excludePids.add(ppid);
+                    // Get grandparent too
+                    const gppidResult = spawnSync("ps", ["-o", "ppid=", "-p", ppid], {
+                        encoding: "utf8",
+                        timeout: 2000,
+                    });
+                    const gppid = gppidResult.stdout?.trim();
+                    if (gppid)
+                        excludePids.add(gppid);
+                }
+            }
+            catch {
+                // Non-fatal - continue with just current PID excluded
+            }
+            // Get current user ID for filtering
+            let currentUid = "";
+            try {
+                const idResult = spawnSync("id", ["-u"], {
+                    encoding: "utf8",
+                    timeout: 2000,
+                });
+                currentUid = idResult.stdout?.trim() || "";
+            }
+            catch {
+                // Non-fatal - will skip user filtering
+            }
+            // Search for orphans using server name pattern (primary) or package identifier (fallback)
+            const patternsToSearch = [serverNamePattern];
+            if (packageIdentifier) {
+                patternsToSearch.push(packageIdentifier);
+            }
+            const orphanPids = new Set();
+            for (const pattern of patternsToSearch) {
+                try {
+                    // Use spawnSync to avoid shell injection - no string interpolation
+                    const pgrepArgs = currentUid
+                        ? ["-f", "-u", currentUid, pattern]
+                        : ["-f", pattern];
+                    const pgrepResult = spawnSync("pgrep", pgrepArgs, {
+                        encoding: "utf8",
+                        timeout: 5000,
+                    });
+                    // pgrep returns exit code 1 if no matches (not an error)
+                    const pids = (pgrepResult.stdout || "")
+                        .trim()
+                        .split("\n")
+                        .filter((pid) => pid && !excludePids.has(pid));
+                    pids.forEach((pid) => orphanPids.add(pid));
+                }
+                catch (pgrepError) {
+                    const errMsg = pgrepError instanceof Error
+                        ? pgrepError.message
+                        : String(pgrepError);
+                    if (errMsg.includes("command not found") ||
+                        errMsg.includes("ENOENT")) {
+                        console.error(`[${config.name}] pgrep not found - cannot detect orphan processes`);
+                    }
+                    // Other errors are non-fatal
+                }
+            }
+            if (orphanPids.size > 0) {
+                const pidList = Array.from(orphanPids);
+                console.log(`[${config.name}] Found ${pidList.length} orphan process(es): PIDs ${pidList.join(", ")}`);
+                // Send SIGTERM to all orphans (using spawnSync for safety)
+                for (const pid of pidList) {
+                    try {
+                        const killResult = spawnSync("kill", ["-TERM", pid], {
+                            timeout: 1000,
+                        });
+                        if (killResult.status === 0) {
+                            console.log(`[${config.name}] Sent SIGTERM to orphan PID: ${pid}`);
+                        }
+                    }
+                    catch {
+                        // Process may have already exited
+                    }
+                }
+                // Wait for graceful termination
+                await new Promise((resolve) => setTimeout(resolve, 800));
+                // Force kill any remaining with SIGKILL
+                for (const pid of pidList) {
+                    try {
+                        // Check if still alive
+                        const checkResult = spawnSync("kill", ["-0", pid], {
+                            timeout: 500,
+                        });
+                        if (checkResult.status === 0) {
+                            // Still alive - force kill
+                            spawnSync("kill", ["-KILL", pid], { timeout: 1000 });
+                            console.log(`[${config.name}] Sent SIGKILL to orphan PID: ${pid}`);
+                        }
+                    }
+                    catch {
+                        // Process already dead
+                    }
+                }
+            }
+            // Inject METALINK_SERVER_NAME into process env for future orphan detection
+            processEnv.METALINK_SERVER_NAME = config.name;
+            processEnv.METALINK_VERSION = version;
+            const childProcess = spawn(config.command, args, spawnOptions);
+            this.processes.set(config.name, childProcess);
+            this.state[config.name] = {
+                pid: childProcess.pid || 0,
+                status: "running",
+                uptime: Date.now(),
+                lastHealthCheck: Date.now(),
+                errorCount: 0,
+            };
+            // Track server start in metrics (Phase 4 - v1.4.0)
+            globalMetrics.recordServerStart(config.name);
+            // Capture stdout and stderr for debugging
+            let stdoutData = "";
+            let stderrData = "";
+            const debugMode = process.env.METALINK_DEBUG === "true";
+            if (childProcess.stdout) {
+                childProcess.stdout.on("data", (chunk) => {
+                    const str = chunk.toString();
+                    stdoutData += str;
+                    if (debugMode) {
+                        console.log(`[DIAG] [${config.name}] Listener #1 (startStdioServer debug) received data:`, str.substring(0, 100));
+                    }
+                    console.log(`[${config.name}] stdout: ${str}`);
+                });
+            }
+            if (childProcess.stderr) {
+                childProcess.stderr.on("data", (chunk) => {
+                    const str = chunk.toString();
+                    stderrData += str;
+                    console.error(`[${config.name}] stderr: ${str}`);
+                });
+            }
+            // Handle process errors
+            childProcess.on("error", (error) => {
+                this.handleServerError(config.name, error);
+            });
+            childProcess.on("exit", (code) => {
+                if (code !== 0 && (stdoutData || stderrData)) {
+                    console.error(`[MetaLink] Server '${config.name}' output on crash:`);
+                    if (stdoutData)
+                        console.error(`  stdout: ${stdoutData}`);
+                    if (stderrData)
+                        console.error(`  stderr: ${stderrData}`);
+                }
+                this.handleServerExit(config.name, code);
+            });
+            // Start health checks if enabled
+            if (config.healthCheck?.enabled) {
+                this.startHealthCheck(config.name, config.healthCheck.interval || 30000);
+            }
+            this.emit("server:started", { name: config.name, pid: childProcess.pid });
+            return this.state[config.name];
+        }
+        catch (error) {
+            throw new Error(`Failed to start stdio server ${config.name}: ${error instanceof Error ? error.message : String(error)}`);
+        }
+    }
+    /**
+     * Start an HTTP-based server (connects via HTTP client)
+     */
+    async startHttpServer(config) {
+        try {
+            // Phase 6: Delegate to HttpConnectionManager
+            const serverProcess = await this.httpConnectionManager.startHttpServer(config);
+            // Keep local state for backward compatibility
+            const client = this.httpConnectionManager.getClient(config.name);
+            if (client) {
+                this.httpClients.set(config.name, client);
+            }
+            // Update local state
+            this.state[config.name] = serverProcess;
+            // Track server start in metrics (Phase 4 - v1.4.0)
+            globalMetrics.recordServerStart(config.name);
+            // Forward events
+            this.httpConnectionManager.on("server:started", ({ name, type, url }) => {
+                this.emit("server:started", { name, type, url });
+            });
+            return serverProcess;
+        }
+        catch (error) {
+            throw new Error(`Failed to start HTTP server ${config.name}: ${error instanceof Error ? error.message : String(error)}`);
+        }
+    }
+    /**
+     * Stop a server process (stdio or HTTP)
+     */
+    async stopServer(serverName) {
+        // Phase 5: Check ProcessManager first, then fall back to local maps
+        const isStdioInManager = this.processManager.isProcessRunning(serverName);
+        const isStdioInLocal = this.processes.has(serverName);
+        const isHttp = this.httpClients.has(serverName);
+        if (!isStdioInManager && !isStdioInLocal && !isHttp) {
+            throw new Error(`Server ${serverName} is not running`);
+        }
+        // Stop health checks
+        const healthCheckInterval = this.healthCheckIntervals.get(serverName);
+        if (healthCheckInterval) {
+            clearInterval(healthCheckInterval);
+            this.healthCheckIntervals.delete(serverName);
+        }
+        if (isStdioInManager) {
+            // Phase 5: Delegate to ProcessManager
+            await this.processManager.stopServer(serverName);
+            // Also clean up local map if present
+            if (isStdioInLocal) {
+                this.processes.delete(serverName);
+            }
+        }
+        else if (isStdioInLocal) {
+            // Legacy: Direct process termination
+            const childProcess = this.processes.get(serverName);
+            // v1.1.27: Clean up all event listeners to prevent memory leaks
+            if (childProcess.stdout) {
+                childProcess.stdout.removeAllListeners();
+            }
+            if (childProcess.stderr) {
+                childProcess.stderr.removeAllListeners();
+            }
+            childProcess.removeAllListeners();
+            childProcess.kill("SIGTERM");
+            // Wait for graceful shutdown
+            await new Promise((resolve) => {
+                const timeout = setTimeout(() => {
+                    childProcess.kill("SIGKILL");
+                    resolve();
+                }, this.timeouts.gracefulShutdown);
+                childProcess.once("exit", () => {
+                    clearTimeout(timeout);
+                    resolve();
+                });
+            });
+            this.processes.delete(serverName);
+        }
+        else if (isHttp) {
+            // Phase 6: Delegate to HttpConnectionManager
+            if (this.httpConnectionManager.hasClient(serverName)) {
+                await this.httpConnectionManager.stopServer(serverName);
+            }
+            // Clean up local map
+            this.httpClients.delete(serverName);
+        }
+        if (this.state[serverName]) {
+            this.state[serverName].status = "stopped";
+        }
+        this.emit("server:stopped", { name: serverName });
+    }
+    /**
+     * Remove a server from the manager
+     * Stops the process if running and cleans up all associated state
+     * Called when a server is removed from the registry
+     */
+    async removeServer(serverName) {
+        // 1. Stop process if running
+        try {
+            await this.stopServer(serverName);
+        }
+        catch (error) {
+            // Server might not be running, continue cleanup anyway
+        }
+        // 2. Clean up active servers tracking
+        this.activeServers.delete(serverName);
+        // 3. Clean up response router listeners
+        const listener = this.stdoutListeners.get(serverName);
+        if (listener) {
+            // Remove listeners from the process if it still exists
+            const process = this.processes.get(serverName);
+            if (process && process.stdout) {
+                process.stdout.removeListener("data", listener.onStdoutData);
+                process.removeListener("error", listener.onError);
+                process.removeListener("exit", listener.onExit);
+            }
+            this.stdoutListeners.delete(serverName);
+        }
+        // 4. Clear pending requests for this server
+        const pendingRequests = this.pendingRequests.get(serverName);
+        if (pendingRequests) {
+            // Reject all pending requests with informative error
+            for (const [requestId, request] of pendingRequests) {
+                clearTimeout(request.timeout);
+                request.reject(new Error(`Server '${serverName}' was removed from registry (pending request ${requestId})`));
+            }
+            this.pendingRequests.delete(serverName);
+        }
+        // 5. Clear stdout buffers
+        this.stdoutBuffers.delete(serverName);
+        // 6. Delete state
+        delete this.state[serverName];
+        // 7. Ensure process is fully removed
+        this.processes.delete(serverName);
+        this.emit("server:removed", { name: serverName });
+    }
+    /**
+     * Restart a server
+     * v1.4.2: Clears schema cache to ensure fresh tool discovery
+     */
+    async restartServer(config) {
+        try {
+            await this.stopServer(config.name);
+        }
+        catch {
+            // Server might not be running, continue anyway
+        }
+        // v1.4.2: Clear schema cache to force fresh discovery on restart
+        this.invalidateServerSchema(config.name);
+        return this.startServer(config);
+    }
+    /**
+     * Invalidate schema cache for a server
+     * Forces fresh discovery on next access
+     * v1.4.2: Added to support force-refresh of tool lists
+     */
+    invalidateServerSchema(serverName) {
+        // Phase 7: Delegate to SchemaCacheManager
+        this.schemaCacheManager.invalidate(serverName);
+        // Legacy: Keep local cache invalidation for backward compatibility
+        const hadCache = this.toolSchemaCache.has(serverName);
+        this.toolSchemaCache.delete(serverName);
+        // Clear from discovered servers set
+        this.discoveredServers.delete(serverName);
+        // Clear discovery timer if exists
+        const timer = this.discoveryTimers.get(serverName);
+        if (timer) {
+            clearTimeout(timer);
+            this.discoveryTimers.delete(serverName);
+        }
+        // Clear stability metrics
+        this.schemaStabilityMetrics.delete(serverName);
+        if (hadCache) {
+            console.log(`[ServerManager] Schema cache invalidated for ${serverName}`);
+        }
+    }
+    /**
+     * Force refresh schema for a server
+     * Invalidates cache and re-discovers tools from running server
+     * v1.4.2: Added to support force-refresh of tool lists
+     */
+    async forceRefreshSchema(serverName, config) {
+        console.log(`[ServerManager] Force refreshing schema for ${serverName}...`);
+        // 1. Invalidate all caches
+        this.invalidateServerSchema(serverName);
+        // 2. Also delete from disk cache
+        if (this.schemaStore) {
+            try {
+                const schemaPath = `${this.schemaStore["cacheDir"]}/${serverName}.json`;
+                const fs = await import("fs/promises");
+                await fs.unlink(schemaPath).catch(() => { }); // Ignore if not exists
+                console.log(`[ServerManager] Deleted disk cache for ${serverName}`);
+            }
+            catch (error) {
+                // Disk cache deletion is best-effort
+            }
+        }
+        // 3. If server is running, fetch tools directly
+        if (this.isServerActive(serverName)) {
+            const process = this.getProcess(serverName);
+            if (process) {
+                try {
+                    const tools = await this.fetchToolsFromProcess(process, serverName);
+                    const schema = { tools, timestamp: Date.now() };
+                    // Update cache
+                    this.toolSchemaCache.set(serverName, schema);
+                    this.discoveredServers.add(serverName);
+                    // Persist to disk
+                    if (this.schemaStore) {
+                        await this.schemaStore.saveToDisk(serverName, schema);
+                    }
+                    console.log(`[ServerManager] Force refreshed ${serverName}: ${tools.length} tools`);
+                    return tools;
+                }
+                catch (error) {
+                    console.warn(`[ServerManager] Failed to fetch tools from running server ${serverName}:`, error);
+                }
+            }
+        }
+        // 4. If not running or fetch failed, do full discovery
+        return this.discoverToolSchemas(serverName, config);
+    }
+    /**
+     * Get server status
+     */
+    getServerStatus(serverName) {
+        return this.state[serverName];
+    }
+    /**
+     * Get all server statuses
+     */
+    getAllServers() {
+        return { ...this.state };
+    }
+    /**
+     * Start health check for a server
+     */
+    startHealthCheck(serverName, interval) {
+        const healthCheckInterval = setInterval(async () => {
+            const result = await this.healthCheck(serverName);
+            this.emit("health:check", result);
+            if (!result.healthy && this.state[serverName]) {
+                this.state[serverName].errorCount++;
+            }
+        }, interval);
+        this.healthCheckIntervals.set(serverName, healthCheckInterval);
+    }
+    /**
+     * Perform health check on a server
+     */
+    async healthCheck(serverName) {
+        const childProcess = this.processes.get(serverName);
+        const state = this.state[serverName];
+        if (!childProcess || !state) {
+            return {
+                serverName,
+                healthy: false,
+                error: "Server not found",
+                timestamp: Date.now(),
+            };
+        }
+        // Simple health check: check if process is still running
+        const healthy = !childProcess.killed;
+        if (state) {
+            state.lastHealthCheck = Date.now();
+        }
+        return {
+            serverName,
+            healthy,
+            timestamp: Date.now(),
+        };
+    }
+    /**
+     * Start health checks for HTTP server
+     */
+    startHttpHealthCheck(serverName, interval) {
+        const healthCheckInterval = setInterval(async () => {
+            const result = await this.httpHealthCheck(serverName);
+            this.emit("health:check", result);
+            if (!result.healthy && this.state[serverName]) {
+                this.state[serverName].errorCount++;
+            }
+        }, interval);
+        this.healthCheckIntervals.set(serverName, healthCheckInterval);
+    }
+    /**
+     * Perform health check on an HTTP server
+     */
+    async httpHealthCheck(serverName) {
+        const client = this.httpClients.get(serverName);
+        const state = this.state[serverName];
+        if (!client || !state) {
+            return {
+                serverName,
+                healthy: false,
+                error: "HTTP client not found",
+                timestamp: Date.now(),
+            };
+        }
+        try {
+            // Use HTTP client's built-in health check
+            const healthy = await client.healthCheck();
+            if (state) {
+                state.lastHealthCheck = Date.now();
+            }
+            return {
+                serverName,
+                healthy,
+                timestamp: Date.now(),
+            };
+        }
+        catch (error) {
+            return {
+                serverName,
+                healthy: false,
+                error: error instanceof Error ? error.message : "Unknown error",
+                timestamp: Date.now(),
+            };
+        }
+    }
+    /**
+     * Handle server errors
+     */
+    handleServerError(serverName, error) {
+        console.error(`[MetaLink] Server '${serverName}' error:`, error.message);
+        if (this.state[serverName]) {
+            this.state[serverName].status = "crashed";
+            this.state[serverName].errorCount++;
+        }
+        // Track server error in metrics with classification (Phase 4 - v1.4.0)
+        const errorType = globalMetrics.classifyErrorType(error);
+        globalMetrics.recordServerError(serverName, error.message, errorType);
+        this.emit("server:error", { name: serverName, error: error.message });
+    }
+    /**
+     * Handle server exit
+     */
+    handleServerExit(serverName, code) {
+        this.processes.delete(serverName);
+        this.activeServers.delete(serverName); // v1.1.33: Clean up stale server data to prevent "process killed" errors
+        if (code !== 0) {
+            console.error(`[MetaLink] Server '${serverName}' exited with code ${code}`);
+        }
+        if (this.state[serverName]) {
+            this.state[serverName].status = code === 0 ? "stopped" : "crashed";
+        }
+        this.emit("server:exited", { name: serverName, code });
+        // Trigger auto-restart if server crashed (non-zero exit code)
+        if (code !== 0) {
+            this.scheduleServerRestart(serverName);
+        }
+    }
+    /**
+     * Get tools for a server
+     * v1.3.60: Check both active servers AND schema cache (for stopped servers)
+     * v1.3.71: Also check disk cache for tools that persist across daemon restarts
+     */
+    getServerTools(serverName) {
+        // Phase 7: Delegate to SchemaCacheManager first
+        const cachedTools = this.schemaCacheManager.getCachedTools(serverName);
+        if (cachedTools && cachedTools.length > 0) {
+            return cachedTools;
+        }
+        // Fallback to active servers (running)
+        const serverData = this.activeServers.get(serverName);
+        if (serverData?.tools && serverData.tools.length > 0) {
+            return serverData.tools;
+        }
+        // Legacy fallback to local caches (will be removed in Phase 8)
+        const cached = this.toolSchemaCache.get(serverName);
+        if (cached?.tools && cached.tools.length > 0) {
+            return cached.tools;
+        }
+        // Fallback to disk cache via SchemaStore
+        if (this.schemaStore) {
+            const diskCached = this.schemaStore.getSyncFromDisk(serverName);
+            if (diskCached && diskCached.length > 0) {
+                // Also populate memory cache for faster subsequent lookups
+                this.toolSchemaCache.set(serverName, {
+                    tools: diskCached,
+                    timestamp: Date.now(),
+                });
+                return diskCached;
+            }
+        }
+        return [];
+    }
+    /**
+     * Set tools for a server
+     * v1.3.62: Persist schemas to disk whenever tools are updated
+     */
+    setServerTools(serverName, tools, process) {
+        let serverData = this.activeServers.get(serverName);
+        if (!serverData) {
+            serverData = {
+                process: process || this.processes.get(serverName),
+                tools: [],
+                toolsReady: false,
+            };
+            this.activeServers.set(serverName, serverData);
+        }
+        else if (process) {
+            // Update process if provided
+            serverData.process = process;
+        }
+        else if (!serverData.process) {
+            // Try to retrieve from processes map if not already set
+            serverData.process = this.processes.get(serverName);
+        }
+        // Phase 2: Enrich tools with safety annotations
+        const enrichedTools = this.enrichToolsWithAnnotations(serverName, tools);
+        serverData.tools = enrichedTools;
+        serverData.toolsReady = true;
+        // v1.3.62: Persist schemas to disk (global cache across versions)
+        // This ensures schemas are saved regardless of how server started:
+        // - Base server initialization
+        // - Direct tool execution (auto-start)
+        // - search_tools (when server already running)
+        // - discover_tools (explicit discovery)
+        const schema = { tools: enrichedTools, timestamp: Date.now() };
+        // Phase 7: Delegate to SchemaCacheManager
+        this.schemaCacheManager.setCachedTools(serverName, enrichedTools, "discovery");
+        // Legacy: Keep local caches for backward compatibility (will be removed in Phase 8)
+        this.toolSchemaCache.set(serverName, schema);
+        if (this.schemaStore) {
+            this.schemaStore.saveToDisk(serverName, schema).catch((error) => {
+                console.warn(`[ServerManager] Failed to persist schema for ${serverName}:`, error);
+            });
+        }
+    }
+    /**
+     * Get all active servers with their tools
+     */
+    getActiveServers() {
+        return new Map(this.activeServers);
+    }
+    /**
+     * Get the process for a specific server
+     * Phase 5: Delegate to ProcessManager first, fallback to local map
+     */
+    getProcess(serverName) {
+        // Try ProcessManager first (Phase 5 delegation)
+        const managerProcess = this.processManager.getProcess(serverName);
+        if (managerProcess) {
+            return managerProcess;
+        }
+        // Legacy fallback to local map
+        return this.processes.get(serverName);
+    }
+    /**
+     * Check if a server is currently active (running and tools loaded)
+     */
+    isServerActive(serverName) {
+        // v1.1.36: Check process.killed flag to ensure dead processes trigger auto-restart
+        const process = this.processes.get(serverName);
+        const hasValidProcess = process && !process.killed;
+        const hasHttpClient = this.httpClients.has(serverName);
+        const hasTools = this.activeServers.has(serverName);
+        return (hasValidProcess || hasHttpClient) && hasTools;
+    }
+    /**
+     * Wait for MCP initialization handshake to complete (without fetching tools)
+     */
+    async waitForInitialization(childProcess, serverName) {
+        return new Promise((resolve, reject) => {
+            const debugMode = process.env.METALINK_DEBUG === "true";
+            let settled = false; // Guard against double-rejection
+            const timeout = setTimeout(() => {
+                if (settled)
+                    return; // Already resolved/rejected, ignore timeout
+                settled = true;
+                const serverInfo = serverName ? ` for ${serverName}` : "";
+                console.error(`[MetaLink] Server initialization timeout after ${this.timeouts.serverInit}ms${serverInfo}`);
+                if (debugMode) {
+                    console.log(`[DIAG] waitForInitialization${serverInfo}: TIMEOUT (no initialize response in ${this.timeouts.serverInit}ms)`);
+                }
+                childProcess.stdout?.removeListener("data", onData);
+                reject(new Error(`Server initialization timeout after ${this.timeouts.serverInit}ms${serverInfo}`));
+            }, this.timeouts.serverInit);
+            let buffer = "";
+            let initialized = false;
+            const handleLines = () => {
+                const lines = buffer.split("\n");
+                for (let i = 0; i < lines.length - 1; i++) {
+                    const line = lines[i].trim();
+                    if (!line || !line.startsWith("{"))
+                        continue;
+                    let response;
+                    try {
+                        response = JSON.parse(line);
+                    }
+                    catch (parseError) {
+                        continue;
+                    }
+                    // Wait for initialize response only
+                    if (!initialized &&
+                        (response.result || response.error) &&
+                        response.id === 0) {
+                        if (settled)
+                            return; // Already timed out or settled
+                        settled = true;
+                        if (debugMode) {
+                            console.log(`[DIAG] waitForInitialization: Detected initialize response (id=0), success=${!!response.result}`);
+                        }
+                        clearTimeout(timeout);
+                        childProcess.stdout?.removeListener("data", onData);
+                        if (response.error) {
+                            reject(new Error(`Server initialization failed: ${JSON.stringify(response.error)}`));
+                        }
+                        else {
+                            console.log(`[MetaLink] Server ${serverName || "unknown"} initialized successfully`);
+                            // Send initialized notification (MCP spec requirement)
+                            const initializedNotif = JSON.stringify({
+                                jsonrpc: "2.0",
+                                method: "notifications/initialized",
+                                params: {},
+                            });
+                            childProcess.stdin?.write(initializedNotif + "\n");
+                            resolve();
+                        }
+                        return;
+                    }
+                }
+                buffer = lines[lines.length - 1];
+            };
+            const onData = (data) => {
+                buffer += data.toString();
+                handleLines();
+            };
+            childProcess.stdout?.on("data", onData);
+            // Send initialize request
+            const initReq = JSON.stringify({
+                jsonrpc: "2.0",
+                id: 0,
+                method: "initialize",
+                params: {
+                    protocolVersion: "2025-06-18",
+                    capabilities: { roots: { listChanged: true } },
+                    clientInfo: { name: "metalink", version: "1.3.49" },
+                },
+            });
+            childProcess.stdin?.write(initReq + "\n");
+        });
+    }
+    /**
+     * Fetch tools from a spawned MCP server via JSON-RPC (PUBLIC)
+     */
+    async fetchToolsFromProcess(childProcess, serverName) {
+        return new Promise((resolve, reject) => {
+            const debugMode = process.env.METALINK_DEBUG === "true";
+            let settled = false; // CRITICAL FIX: Guard against double-rejection
+            // Capture stderr for debugging (especially for npm-based servers)
+            let stderrOutput = "";
+            if (childProcess.stderr) {
+                childProcess.stderr.on("data", (chunk) => {
+                    stderrOutput += chunk.toString();
+                });
+            }
+            // v1.1.27: Track SIGKILL timeout to prevent race condition
+            let killTimeout = null;
+            // Timeout: 60s for npm-based servers (download + install + startup)
+            const timeout = setTimeout(() => {
+                if (settled)
+                    return; // CRITICAL FIX: Already resolved/rejected, ignore timeout
+                settled = true;
+                const serverInfo = serverName ? ` for ${serverName}` : "";
+                console.error(`[MetaLink] Server initialization timeout after 60s${serverInfo}`);
+                if (debugMode) {
+                    console.log(`[DIAG] fetchToolsFromProcess${serverInfo}: TIMEOUT (no tools/list response in 60s)`);
+                }
+                if (stderrOutput) {
+                    console.error(`[MetaLink] Server stderr${serverInfo}:\n${stderrOutput}`);
+                }
+                try {
+                    childProcess.kill("SIGTERM");
+                    // v1.1.27: Store SIGKILL timeout reference
+                    killTimeout = setTimeout(() => {
+                        if (!childProcess.killed) {
+                            childProcess.kill("SIGKILL");
+                        }
+                    }, 2000);
+                }
+                catch (killError) {
+                    console.error(`[MetaLink] Error killing timed-out process: ${killError instanceof Error ? killError.message : String(killError)}`);
+                }
+                reject(new Error(`Server initialization timeout after ${this.timeouts.toolFetch}ms${serverInfo}`));
+            }, this.timeouts.toolFetch);
+            // v1.1.27: Helper to clear all timeouts
+            const clearAllTimeouts = () => {
+                clearTimeout(timeout);
+                if (killTimeout) {
+                    clearTimeout(killTimeout);
+                    killTimeout = null;
+                }
+            };
+            let buffer = "";
+            let initialized = false;
+            const handleLines = () => {
+                const lines = buffer.split("\n");
+                for (let i = 0; i < lines.length - 1; i++) {
+                    const line = lines[i].trim();
+                    if (!line || !line.startsWith("{"))
+                        continue;
+                    let response;
+                    try {
+                        response = JSON.parse(line);
+                    }
+                    catch (parseError) {
+                        console.error(`[MetaLink] Failed to parse JSON: ${parseError instanceof Error ? parseError.message : String(parseError)}`);
+                        continue;
+                    }
+                    // Wait for initialize response first
+                    if (!initialized &&
+                        (response.result || response.error) &&
+                        response.id === 0) {
+                        if (response.error) {
+                            if (settled)
+                                return; // CRITICAL FIX: Already resolved/rejected
+                            settled = true;
+                            clearAllTimeouts(); // v1.1.27: Use helper to clear all timeouts
+                            childProcess.stdout?.removeListener("data", onData);
+                            reject(new Error(`Server initialization failed: ${JSON.stringify(response.error)}`));
+                            return;
+                        }
+                        else {
+                            initialized = true;
+                            console.error(`[MetaLink] Server initialized successfully, requesting tools...`);
+                            // Send initialized notification (MCP spec requirement)
+                            const initializedNotif = JSON.stringify({
+                                jsonrpc: "2.0",
+                                method: "notifications/initialized",
+                                params: {},
+                            });
+                            childProcess.stdin?.write(initializedNotif + "\n");
+                            // Request tools/list
+                            const listReq = JSON.stringify({
+                                jsonrpc: "2.0",
+                                id: 1,
+                                method: "tools/list",
+                                params: {},
+                            });
+                            childProcess.stdin?.write(listReq + "\n");
+                            continue;
+                        }
+                    }
+                    // Handle tools/list response
+                    if (response.id === 1) {
+                        if (debugMode) {
+                            console.log(`[DIAG] fetchToolsFromProcess: Detected tools/list response (id=1), has_error=${!!response.error}, has_result=${!!response.result}`);
+                        }
+                        if (response.error) {
+                            if (settled)
+                                return; // CRITICAL FIX: Already resolved/rejected
+                            settled = true;
+                            clearAllTimeouts(); // v1.1.27: Use helper to clear all timeouts
+                            childProcess.stdout?.removeListener("data", onData);
+                            reject(new Error(`Failed to get tools list: ${JSON.stringify(response.error)}`));
+                            return;
+                        }
+                        const resultTools = response.result
+                            ?.tools;
+                        if (resultTools && Array.isArray(resultTools)) {
+                            if (settled)
+                                return; // CRITICAL FIX: Already resolved/rejected
+                            settled = true;
+                            clearAllTimeouts(); // v1.1.27: Use helper to clear all timeouts
+                            childProcess.stdout?.removeListener("data", onData);
+                            console.error(`[MetaLink] Successfully received ${resultTools.length} tools`);
+                            if (debugMode) {
+                                console.log(`[DIAG] fetchToolsFromProcess: Returning ${resultTools.length} tools to caller`);
+                            }
+                            // v1.3.58: Health check - warn if server returns 0 tools
+                            if (resultTools.length === 0) {
+                                console.error(`[MetaLink] ⚠️  WARNING: Server returned 0 tools!`);
+                                console.error(`[MetaLink]     This may indicate:`);
+                                console.error(`[MetaLink]     • Server still initializing (may need more time)`);
+                                console.error(`[MetaLink]     • Backend service connection failed`);
+                                console.error(`[MetaLink]     • Environment variables (API keys, URLs) incorrect`);
+                                console.error(`[MetaLink]     • Server does not implement tools/list correctly`);
+                                console.error(`[MetaLink]     Debug with: metalink server debug <server-name>`);
+                            }
+                            // v1.4.0: Schema validation
+                            this.validateToolSchemas(resultTools, serverName);
+                            resolve(resultTools);
+                            return;
+                        }
+                    }
+                }
+                buffer = lines[lines.length - 1];
+            };
+            const onData = (data) => {
+                buffer += data.toString();
+                handleLines();
+            };
+            childProcess.stdout?.on("data", onData);
+            childProcess.stderr?.on("data", (data) => {
+                const msg = data.toString().trim();
+                if (msg)
+                    console.error(`[MetaLink] [${childProcess.pid}] stderr: ${msg}`);
+            });
+            // Send initialize request
+            const initReq = JSON.stringify({
+                jsonrpc: "2.0",
+                id: 0,
+                method: "initialize",
+                params: {
+                    protocolVersion: "2025-06-18",
+                    capabilities: { roots: { listChanged: true } },
+                    clientInfo: { name: "metalink", version },
+                },
+            });
+            childProcess.stdin?.write(initReq + "\n");
+        });
+    }
+    /**
+     * Initialize base servers before daemon startup
+     * Starts all configured base servers unconditionally for immediate availability
+     */
+    async initializeBaseServers(configLoader) {
+        if (this.baseServersEnabled) {
+            console.log("[MetaLink] Base servers already initialized");
+            return;
+        }
+        if (this.baseServers.length === 0) {
+            console.log("[MetaLink] No base servers configured, skipping initialization");
+            this.baseServersEnabled = true;
+            return;
+        }
+        console.log(`[MetaLink] Initializing base servers: ${this.baseServers.join(", ")}`);
+        // Get all available servers (config + registry)
+        const allServers = configLoader.getAllServers();
+        const serverConfigs = new Map(allServers.map((s) => [s.name, s]));
+        // Start base servers in parallel for faster startup (80% improvement: 5-15s → <2s)
+        const startResults = await Promise.allSettled(this.baseServers.map(async (baseServerName) => {
+            const config = serverConfigs.get(baseServerName);
+            if (!config) {
+                console.warn(`[MetaLink] Base server '${baseServerName}' not found in available servers, skipping`);
+                return { server: baseServerName, status: "skipped" };
+            }
+            try {
+                console.log(`[MetaLink] Starting base server: ${baseServerName}`);
+                await this.startServer(config);
+                // Fetch tools from the started server
+                const serverProcess = this.processes.get(baseServerName);
+                if (serverProcess) {
+                    const tools = await this.fetchToolsFromProcess(serverProcess, baseServerName);
+                    this.setServerTools(baseServerName, tools);
+                    console.log(`[MetaLink] Base server '${baseServerName}' ready with ${tools.length} tools`);
+                    return {
+                        server: baseServerName,
+                        status: "success",
+                        toolCount: tools.length,
+                    };
+                }
+                return { server: baseServerName, status: "no-process" };
+            }
+            catch (error) {
+                console.error(`[MetaLink] Failed to start base server '${baseServerName}': ${error instanceof Error ? error.message : String(error)}`);
+                return {
+                    server: baseServerName,
+                    status: "failed",
+                    error: error instanceof Error ? error.message : String(error),
+                };
+            }
+        }));
+        // Count successful starts
+        const startedCount = startResults.filter((r) => r.status === "fulfilled" && r.value?.status === "success").length;
+        this.baseServersEnabled = true;
+        console.log(`[MetaLink] Base servers initialization complete (${startedCount}/${this.baseServers.length} started)`);
+    }
+    /**
+     * Check if base servers are enabled
+     */
+    areBaseServersEnabled() {
+        return this.baseServersEnabled;
+    }
+    /**
+     * Background population of missing schemas (v1.3.62)
+     * Compares registry servers with cached schemas and populates missing ones
+     * Runs in background, one server at a time, non-blocking
+     */
+    async populateMissingSchemas(configLoader) {
+        console.log("[SchemaPopulation] Starting background schema population...");
+        // Get all servers from registry
+        const allServers = configLoader.getAllServers();
+        const serverNames = Array.from(allServers.keys());
+        // Find servers missing from cache
+        const missingServers = serverNames.filter((name) => !this.toolSchemaCache.has(name));
+        if (missingServers.length === 0) {
+            console.log("[SchemaPopulation] All servers already have cached schemas");
+            return;
+        }
+        console.log(`[SchemaPopulation] Found ${missingServers.length} servers with missing schemas:`, missingServers);
+        // Start servers one by one in background
+        let populated = 0;
+        for (const serverName of missingServers) {
+            try {
+                const config = allServers.get(serverName);
+                if (!config)
+                    continue;
+                console.log(`[SchemaPopulation] [${populated + 1}/${missingServers.length}] Populating schema for ${serverName}...`);
+                // Start server and fetch tools
+                await this.ensureServerStarted(serverName, config);
+                const tools = this.getServerTools(serverName);
+                if (tools.length > 0) {
+                    console.log(`[SchemaPopulation] ✅ Cached ${tools.length} tools from ${serverName}`);
+                    populated++;
+                    // v1.1.33: Don't kill servers after caching - improves reliability
+                    // Previously would stop server here to save resources, but this caused
+                    // "process has been killed" errors when tools were called
+                    // this.stopServer(serverName);
+                    // console.log(`[SchemaPopulation] Stopped ${serverName} (schema cached)`);
+                }
+                else {
+                    console.warn(`[SchemaPopulation] ⚠️  ${serverName} returned 0 tools`);
+                }
+            }
+            catch (error) {
+                console.error(`[SchemaPopulation] Failed to populate ${serverName}:`, error instanceof Error ? error.message : String(error));
+            }
+        }
+        console.log(`[SchemaPopulation] Complete: ${populated}/${missingServers.length} schemas populated`);
+    }
+    /**
+     * Get schema for a specific tool
+     * v1.1.47: Add disk fallback to match getServerTools() behavior
+     * This fixes the bug where CLI shows tools but MCP can't find them
+     */
+    getToolSchema(serverName, toolName) {
+        // First check active servers (running)
+        const serverData = this.activeServers.get(serverName);
+        if (serverData?.tools) {
+            const tool = serverData.tools.find((t) => t.name === toolName);
+            if (tool)
+                return tool;
+        }
+        // Fallback to schema cache (persistent cache for stopped servers)
+        const cached = this.toolSchemaCache.get(serverName);
+        if (cached?.tools) {
+            const tool = cached.tools.find((t) => t.name === toolName);
+            if (tool)
+                return tool;
+        }
+        // v1.1.47: Fallback to disk cache (persists across daemon restarts)
+        // This ensures getToolSchema() has same fallback chain as getServerTools()
+        if (this.schemaStore) {
+            const diskCached = this.schemaStore.getSyncFromDisk(serverName);
+            if (diskCached && diskCached.length > 0) {
+                // Populate memory cache for faster subsequent lookups
+                this.toolSchemaCache.set(serverName, {
+                    tools: diskCached,
+                    timestamp: Date.now(),
+                });
+                const tool = diskCached.find((t) => t.name === toolName);
+                if (tool)
+                    return tool;
+            }
+        }
+        return null;
+    }
+    /**
+     * Detect if arguments are missing when tool requires them
+     */
+    detectMissingArguments(args, toolSchema) {
+        if (!args || typeof args !== "object") {
+            return false;
+        }
+        const hasArguments = "arguments" in args;
+        const argumentsValue = args.arguments;
+        const inputSchema = toolSchema?.inputSchema;
+        const requiresArguments = inputSchema?.required && inputSchema.required.length > 0;
+        if (!hasArguments && requiresArguments && inputSchema?.required) {
+            console.error(`[MetaLink] Missing 'arguments' parameter. Tool: ${args.server_name || "unknown"}-${args.tool_name || "unknown"}, ` +
+                `Required params: ${inputSchema.required.join(", ")}`);
+            return true;
+        }
+        if (hasArguments &&
+            (argumentsValue === null || argumentsValue === undefined) &&
+            requiresArguments &&
+            inputSchema?.required) {
+            console.error(`[MetaLink] 'arguments' parameter is null/undefined. Tool: ${args.server_name || "unknown"}-${args.tool_name || "unknown"}, ` +
+                `Required params: ${inputSchema.required.join(", ")}`);
+            return true;
+        }
+        return false;
+    }
+    /**
+     * Detect and fix Raycast's malformed argument format
+     * Raycast sometimes wraps tool_name and server_name inside the arguments object
+     */
+    detectAndFixRaycastFormat(args) {
+        if (!args || typeof args !== "object" || Array.isArray(args)) {
+            return args;
+        }
+        // Check if args.arguments exists and contains tool_name or server_name (malformed)
+        const argObj = args.arguments;
+        if (argObj && typeof argObj === "object" && !Array.isArray(argObj)) {
+            const hasToolName = "tool_name" in argObj;
+            const hasServerName = "server_name" in argObj;
+            if (hasToolName || hasServerName) {
+                // This is Raycast's malformed format - fix it
+                const toolName = argObj.tool_name;
+                const serverName = argObj.server_name;
+                // Extract tool parameters (anything that's not tool_name or server_name)
+                const toolParams = {};
+                for (const [key, value] of Object.entries(argObj)) {
+                    if (key !== "tool_name" && key !== "server_name") {
+                        toolParams[key] = value;
+                    }
+                }
+                // Determine final arguments - unwrap if toolParams contains nested 'arguments'
+                let finalArguments;
+                if ("arguments" in toolParams &&
+                    typeof toolParams.arguments === "object") {
+                    // Raycast sent nested arguments - unwrap it
+                    finalArguments = toolParams.arguments;
+                }
+                else if (Object.keys(toolParams).length > 0) {
+                    // Tool params at this level - use them directly
+                    finalArguments = toolParams;
+                }
+                else {
+                    // No params found - use empty object
+                    finalArguments = {};
+                }
+                // Reconstruct correct structure
+                const fixedArgs = {
+                    ...args,
+                    server_name: serverName || args.server_name,
+                    tool_name: toolName || args.tool_name,
+                    arguments: finalArguments,
+                };
+                console.error(`[MetaLink] [Raycast Workaround] Fixed malformed argument format for ${fixedArgs.server_name}-${fixedArgs.tool_name}` +
+                    ` | Unwrapped nested arguments: ${Object.keys(finalArguments).length} params`);
+                if (Object.keys(finalArguments).length === 0) {
+                    console.error(`[MetaLink] [Raycast Issue] WARNING: No tool parameters found after fixing malformed format. ` +
+                        `Tool: ${fixedArgs.server_name}-${fixedArgs.tool_name} | ` +
+                        `This may indicate Raycast failed to populate arguments from describe_tool response.`);
+                }
+                return fixedArgs;
+            }
+        }
+        // Case B: Check if tool params are at TOP level instead of in arguments
+        // This happens when Raycast passes: {"server_name": "X", "tool_name": "Y", "cql": "..."}
+        // instead of: {"server_name": "X", "tool_name": "Y", "arguments": {"cql": "..."}}
+        if (!args.arguments) {
+            // Extract tool parameters (anything that's not server_name, tool_name, or arguments)
+            const topLevelParams = {};
+            for (const [key, value] of Object.entries(args)) {
+                if (key !== "tool_name" &&
+                    key !== "server_name" &&
+                    key !== "arguments") {
+                    topLevelParams[key] = value;
+                }
+            }
+            // If we found top-level params, wrap them in arguments
+            if (Object.keys(topLevelParams).length > 0) {
+                console.error(`[MetaLink] [Raycast Workaround] Fixed flat argument format for ${args.server_name}-${args.tool_name}. ` +
+                    `Moved top-level params to arguments: ${Object.keys(topLevelParams).join(", ")}`);
+                return {
+                    server_name: args.server_name,
+                    tool_name: args.tool_name,
+                    arguments: topLevelParams,
+                };
+            }
+        }
+        return args;
+    }
+    /**
+     * Phase 3: Set up response router for a server
+     * Listens to stdout, parses JSON-RPC responses, and matches them to pending requests
+     */
+    setupServerResponseRouter(serverName) {
+        const serverData = this.activeServers.get(serverName);
+        if (!serverData || !serverData.process) {
+            return; // No process to set up router for
+        }
+        // Check if router already exists - but verify it's for the CURRENT process
+        // After server restart, old router points to dead process and must be reset
+        if (this.stdoutListeners.has(serverName)) {
+            const currentPid = serverData.process.pid;
+            const storedPid = this.stdoutListeners.get(serverName)?.processPid;
+            if (storedPid === currentPid) {
+                console.log(`[MetaLink] Response router already exists for ${serverName} (pid=${currentPid})`);
+                return;
+            }
+            // Process changed - clean up stale router and set up fresh one
+            console.log(`[MetaLink] Response router stale for ${serverName} (old pid=${storedPid}, new pid=${currentPid}), resetting...`);
+            this.cleanupServerResponseRouter(serverName);
+        }
+        // Initialize pending requests map for this server
+        if (!this.pendingRequests.has(serverName)) {
+            this.pendingRequests.set(serverName, new Map());
+        }
+        // Initialize buffer for this server
+        if (!this.stdoutBuffers.has(serverName)) {
+            this.stdoutBuffers.set(serverName, "");
+        }
+        const maxBufferSize = 10 * 1024 * 1024; // 10MB limit per server (increased from 1MB for large results like read_graph)
+        // Create shared listener function
+        const onStdoutData = (data) => {
+            let buffer = this.stdoutBuffers.get(serverName) || "";
+            buffer += data.toString();
+            // Warn if buffer is getting large (50% of max)
+            const warnThreshold = maxBufferSize * 0.5;
+            if (buffer.length > warnThreshold && buffer.length <= maxBufferSize) {
+                console.warn(`[MetaLink] Large buffer for ${serverName}: ${(buffer.length / 1024 / 1024).toFixed(2)}MB (${((buffer.length / maxBufferSize) * 100).toFixed(0)}% of max). Consider pagination for large results.`);
+            }
+            // Check buffer size limit
+            if (buffer.length > maxBufferSize) {
+                console.error(`[MetaLink] Buffer exceeded max size (${(buffer.length / 1024 / 1024).toFixed(2)}MB > ${(maxBufferSize / 1024 / 1024).toFixed(2)}MB) for ${serverName}, rejecting pending requests`);
+                const pending = this.pendingRequests.get(serverName);
+                if (pending) {
+                    for (const [_requestId, requestInfo] of pending) {
+                        clearTimeout(requestInfo.timeout);
+                        requestInfo.reject(new Error(`Buffer exceeded max size: ${(buffer.length / 1024 / 1024).toFixed(2)}MB > ${(maxBufferSize / 1024 / 1024).toFixed(2)}MB. Consider using pagination or filtering for large results.`));
+                    }
+                    pending.clear();
+                }
+                this.stdoutBuffers.set(serverName, "");
+                this.cleanupServerResponseRouter(serverName);
+                return;
+            }
+            // Extract complete JSON objects using brace-depth tracking
+            // This handles both single-line and multiline JSON-RPC responses
+            const extractCompleteJsonObjects = (buf) => {
+                const objects = [];
+                let position = 0;
+                while (position < buf.length) {
+                    // Skip whitespace
+                    while (position < buf.length && /\s/.test(buf[position])) {
+                        position++;
+                    }
+                    if (position >= buf.length)
+                        break;
+                    // Must start with '{'
+                    if (buf[position] !== "{") {
+                        // Skip non-JSON content (e.g., log messages from server)
+                        const nextBrace = buf.indexOf("{", position);
+                        if (nextBrace === -1) {
+                            // No more JSON objects, keep remainder
+                            break;
+                        }
+                        position = nextBrace;
+                        continue;
+                    }
+                    // Track brace depth and extract complete object
+                    let braceDepth = 0;
+                    let inString = false;
+                    let escaped = false;
+                    const objectStart = position;
+                    while (position < buf.length) {
+                        const char = buf[position];
+                        // Handle escape sequences
+                        if (escaped) {
+                            escaped = false;
+                            position++;
+                            continue;
+                        }
+                        if (char === "\\" && inString) {
+                            escaped = true;
+                            position++;
+                            continue;
+                        }
+                        // Track string state
+                        if (char === '"' && !escaped) {
+                            inString = !inString;
+                            position++;
+                            continue;
+                        }
+                        if (inString) {
+                            position++;
+                            continue;
+                        }
+                        // Track brace depth (outside strings)
+                        if (char === "{") {
+                            braceDepth++;
+                        }
+                        else if (char === "}") {
+                            braceDepth--;
+                        }
+                        position++;
+                        // Complete object found
+                        if (braceDepth === 0) {
+                            const jsonStr = buf.substring(objectStart, position).trim();
+                            try {
+                                const obj = JSON.parse(jsonStr);
+                                if (obj.id !== undefined ||
+                                    obj.error !== undefined ||
+                                    obj.result !== undefined) {
+                                    objects.push(obj);
+                                    console.log(`[MetaLink] Extracted complete JSON object for ${serverName}: id=${obj.id}`);
+                                }
+                            }
+                            catch (parseError) {
+                                console.error(`[MetaLink] Failed to parse JSON object in ${serverName}:`, `Position ${objectStart}-${position}:`, jsonStr.substring(0, 100) +
+                                    (jsonStr.length > 100 ? "..." : ""), parseError instanceof Error
+                                    ? parseError.message
+                                    : String(parseError));
+                            }
+                            break;
+                        }
+                    }
+                    // If we didn't complete the object, break and keep remainder in buffer
+                    if (braceDepth > 0) {
+                        position = objectStart; // Reset to start of incomplete object
+                        break;
+                    }
+                }
+                return {
+                    objects,
+                    remaining: buf.substring(position).trim(),
+                };
+            };
+            // Extract complete JSON objects from buffer
+            const { objects, remaining } = extractCompleteJsonObjects(buffer);
+            this.stdoutBuffers.set(serverName, remaining);
+            const pending = this.pendingRequests.get(serverName);
+            if (!pending || pending.size === 0) {
+                return; // No pending requests
+            }
+            // Process extracted JSON objects
+            for (const response of objects) {
+                const requestId = response.id;
+                // Check if this response matches any pending request
+                if (requestId !== undefined && pending.has(requestId)) {
+                    const requestInfo = pending.get(requestId);
+                    if (requestInfo) {
+                        clearTimeout(requestInfo.timeout);
+                        pending.delete(requestId);
+                        console.log(`[MetaLink] Response router: matched requestId=${requestId} for ${serverName}-${requestInfo.toolName} (${pending.size} remaining)`);
+                        // Route response to the correct promise
+                        if (response.error) {
+                            requestInfo.reject(new Error(JSON.stringify(response.error)));
+                        }
+                        else {
+                            requestInfo.resolve({
+                                content: [
+                                    {
+                                        type: "text",
+                                        text: JSON.stringify(response.result),
+                                    },
+                                ],
+                            });
+                        }
+                    }
+                }
+            }
+        };
+        // Set up error and exit handlers
+        const onError = (error) => {
+            console.error(`[MetaLink] Process error for ${serverName}: ${error.message}`);
+            const pending = this.pendingRequests.get(serverName);
+            if (pending) {
+                for (const [_requestId, requestInfo] of pending) {
+                    clearTimeout(requestInfo.timeout);
+                    requestInfo.reject(new Error(`Server error: ${error.message}`));
+                }
+                pending.clear();
+            }
+            this.cleanupServerResponseRouter(serverName);
+        };
+        const onExit = (code) => {
+            console.error(`[MetaLink] Process exited for ${serverName} (code=${code})`);
+            const pending = this.pendingRequests.get(serverName);
+            if (pending) {
+                for (const [_requestId, requestInfo] of pending) {
+                    clearTimeout(requestInfo.timeout);
+                    requestInfo.reject(new Error(`Server exited unexpectedly (code=${code})`));
+                }
+                pending.clear();
+            }
+            this.activeServers.delete(serverName);
+            this.cleanupServerResponseRouter(serverName);
+        };
+        // Attach listeners
+        serverData.process.stdout?.on("data", onStdoutData);
+        serverData.process.on("error", onError);
+        serverData.process.on("exit", onExit);
+        // Store listener references for cleanup (including PID to detect stale routers)
+        this.stdoutListeners.set(serverName, {
+            onStdoutData,
+            onError,
+            onExit,
+            processPid: serverData.process.pid,
+        });
+        console.log(`[MetaLink] Response router set up for ${serverName} (using JSON boundary detection)`);
+    }
+    /**
+     * Phase 3: Clean up response router for a server
+     */
+    cleanupServerResponseRouter(serverName) {
+        const serverData = this.activeServers.get(serverName);
+        const listenerInfo = this.stdoutListeners.get(serverName);
+        if (listenerInfo && serverData?.process) {
+            // Remove listeners
+            serverData.process.stdout?.removeListener("data", listenerInfo.onStdoutData);
+            serverData.process.removeListener("error", listenerInfo.onError);
+            serverData.process.removeListener("exit", listenerInfo.onExit);
+            console.log(`[MetaLink] Response router cleaned up for ${serverName}`);
+        }
+        // Clear state
+        this.stdoutListeners.delete(serverName);
+        this.stdoutBuffers.delete(serverName);
+    }
+    /**
+     * Phase 3: Call a tool on a server and wait for response
+     * Supports both stdio (process) and HTTP (httpClient) servers
+     */
+    async callTool(serverName, toolName, toolArgs) {
+        if (!serverName || !toolName) {
+            throw new Error(`Invalid tool call: server_name='${serverName}', tool_name='${toolName}'`);
+        }
+        // Check circuit breaker before attempting tool call
+        const breaker = this.circuitBreakerManager.getBreaker(serverName);
+        if (!breaker.canExecute()) {
+            const metrics = breaker.getMetrics();
+            const timeUntilReset = metrics.lastFailureTime
+                ? Math.max(0, 30000 - (Date.now() - metrics.lastFailureTime))
+                : 0;
+            throw new Error(`Circuit breaker is OPEN for ${serverName}. ` +
+                `Server has failed ${metrics.failures} consecutive times. ` +
+                `Retry in ${Math.ceil(timeUntilReset / 1000)}s.`);
+        }
+        let serverData = this.activeServers.get(serverName);
+        // v1.1.56: State recovery - if server process exists but not in activeServers, attempt recovery
+        if (!serverData) {
+            const process = this.processes.get(serverName);
+            const httpClient = this.httpClients.get(serverName);
+            // Check if process/client exists but activeServers is out of sync
+            if (process && !process.killed) {
+                console.warn(`[MetaLink] State corruption detected: ${serverName} has process (PID ${process.pid}) but not in activeServers. Attempting recovery...`);
+                // Try to recover from schema cache
+                const cached = this.toolSchemaCache.get(serverName);
+                if (cached?.tools && cached.tools.length > 0) {
+                    this.setServerTools(serverName, cached.tools, process);
+                    serverData = this.activeServers.get(serverName);
+                    console.log(`[MetaLink] State recovered for ${serverName}: ${cached.tools.length} tools restored`);
+                }
+                else {
+                    console.error(`[MetaLink] Cannot recover ${serverName}: no cached schema. Fetching tools...`);
+                    try {
+                        const tools = await this.fetchToolsFromProcess(process, serverName);
+                        this.setServerTools(serverName, tools, process);
+                        serverData = this.activeServers.get(serverName);
+                        console.log(`[MetaLink] State recovered for ${serverName}: fetched ${tools.length} tools`);
+                    }
+                    catch (error) {
+                        console.error(`[MetaLink] Failed to fetch tools for recovery:`, error);
+                        throw new Error(`Server '${serverName}' state corrupted and recovery failed: ${error instanceof Error ? error.message : String(error)}`);
+                    }
+                }
+            }
+            else if (httpClient) {
+                console.warn(`[MetaLink] State corruption detected: ${serverName} has HTTP client but not in activeServers. Attempting recovery...`);
+                // Try to recover from schema cache for HTTP servers
+                const cached = this.toolSchemaCache.get(serverName);
+                if (cached?.tools && cached.tools.length > 0) {
+                    this.setServerTools(serverName, cached.tools);
+                    serverData = this.activeServers.get(serverName);
+                    console.log(`[MetaLink] State recovered for ${serverName}: ${cached.tools.length} tools restored`);
+                }
+                else {
+                    console.error(`[MetaLink] Cannot recover ${serverName}: no cached schema for HTTP server`);
+                    throw new Error(`Server '${serverName}' HTTP client state corrupted and no cached schema available`);
+                }
+            }
+            else {
+                // No process or client exists - server truly not active
+                const activeList = Array.from(this.activeServers.keys()).join(", ") || "none";
+                throw new Error(`Server '${serverName}' is not active. Active servers: ${activeList}. Enable it first with enable_server.`);
+            }
+        }
+        // Final type assertion after recovery
+        if (!serverData) {
+            throw new Error(`Server '${serverName}' state recovery failed - activeServers is still empty`);
+        }
+        // Check if this is an HTTP server
+        const httpClient = this.httpClients.get(serverName);
+        if (httpClient) {
+            // HTTP server: use httpClient.call()
+            console.log(`[MetaLink] Calling tool '${toolName}' on HTTP server '${serverName}'`);
+            try {
+                const response = await httpClient.call("tools/call", {
+                    name: toolName,
+                    arguments: toolArgs,
+                });
+                if (response.error) {
+                    breaker.recordFailure();
+                    throw new Error(`Tool error: ${response.error.message}`);
+                }
+                breaker.recordSuccess();
+                // Reset restart tracking on successful tool execution
+                this.resetRestartTracking(serverName);
+                return response.result;
+            }
+            catch (error) {
+                breaker.recordFailure();
+                throw new Error(`HTTP tool call failed: ${error instanceof Error ? error.message : String(error)}`);
+            }
+        }
+        // stdio server: use process stdin/stdout
+        if (!serverData.process) {
+            throw new Error(`Server '${serverName}' has no process associated`);
+        }
+        // v1.4.1: Auto-restart killed servers instead of throwing
+        // This fixes "process has been killed" errors when server crashes mid-session
+        if (serverData.process.killed) {
+            console.log(`[MetaLink] Server '${serverName}' process was killed, auto-restarting...`);
+            // Get server config for restart
+            if (!this.serverListProvider) {
+                throw new Error(`Server '${serverName}' process has been killed and cannot auto-restart (no config provider)`);
+            }
+            const allConfigs = this.serverListProvider();
+            const config = allConfigs.find((c) => c.name === serverName);
+            if (!config) {
+                throw new Error(`Server '${serverName}' process has been killed and cannot auto-restart (config not found)`);
+            }
+            // Clean up dead process state
+            this.processes.delete(serverName);
+            this.activeServers.delete(serverName);
+            // Restart the server synchronously before tool call
+            await this.ensureServerStarted(serverName, config);
+            // Get refreshed server data after restart
+            serverData = this.activeServers.get(serverName);
+            if (!serverData?.process || serverData.process.killed) {
+                throw new Error(`Server '${serverName}' failed to restart`);
+            }
+            console.log(`[MetaLink] Server '${serverName}' auto-restarted successfully`);
+        }
+        console.log(`[MetaLink] Calling tool '${toolName}' on server '${serverName}'`);
+        // Ensure response router is set up for this server
+        this.setupServerResponseRouter(serverName);
+        // Generate unique request ID using monotonic counter (v1.1.49: fixes collision bug)
+        const counter = (this.requestIdCounters.get(serverName) || 0) + 1;
+        this.requestIdCounters.set(serverName, counter);
+        const requestId = counter;
+        return new Promise((resolve, reject) => {
+            // Set up timeout (5 minutes)
+            const timeout = setTimeout(() => {
+                const pending = this.pendingRequests.get(serverName);
+                if (pending && pending.has(requestId)) {
+                    pending.delete(requestId);
+                    console.error(`[MetaLink] Tool call timeout after ${this.timeouts.toolExecution}ms: ${serverName}-${toolName} (requestId=${requestId})`);
+                }
+                breaker.recordFailure();
+                reject(new Error(`Tool call timeout after ${this.timeouts.toolExecution}ms: ${serverName}-${toolName}`));
+            }, this.timeouts.toolExecution);
+            // Register this request in pendingRequests
+            if (!this.pendingRequests.has(serverName)) {
+                this.pendingRequests.set(serverName, new Map());
+            }
+            const pending = this.pendingRequests.get(serverName);
+            // Create wrapped reject that cleans up and records failure
+            const wrappedReject = (error) => {
+                clearTimeout(timeout);
+                if (pending.has(requestId)) {
+                    pending.delete(requestId);
+                    console.log(`[MetaLink] Request ${requestId} rejected for ${serverName}-${toolName}`);
+                }
+                breaker.recordFailure();
+                reject(error);
+            };
+            // Create wrapped resolve that records success
+            const wrappedResolve = (result) => {
+                clearTimeout(timeout);
+                if (pending.has(requestId)) {
+                    pending.delete(requestId);
+                }
+                breaker.recordSuccess();
+                // Reset restart tracking on successful tool execution
+                this.resetRestartTracking(serverName);
+                resolve(result);
+            };
+            pending.set(requestId, {
+                resolve: wrappedResolve,
+                reject: wrappedReject,
+                timeout,
+                toolName,
+                startTime: Date.now(),
+            });
+            console.log(`[MetaLink] Registered request ${requestId} for ${serverName}-${toolName} (${pending.size} total pending)`);
+            // Send the request
+            const request = JSON.stringify({
+                jsonrpc: "2.0",
+                id: requestId,
+                method: "tools/call",
+                params: {
+                    name: toolName,
+                    arguments: toolArgs,
+                },
+            });
+            try {
+                console.log(`[MetaLink] Writing tool call request (id=${requestId}) to ${serverName}-${toolName}`);
+                if (!serverData.process) {
+                    throw new Error(`Server process not available for ${serverName}`);
+                }
+                serverData.process.stdin?.write(request + "\n");
+            }
+            catch (writeError) {
+                // Clean up on write error
+                if (pending.has(requestId)) {
+                    clearTimeout(timeout);
+                    pending.delete(requestId);
+                }
+                breaker.recordFailure();
+                reject(new Error(`Failed to write tool call request: ${writeError instanceof Error ? writeError.message : String(writeError)}`));
+            }
+        });
+    }
+    /**
+     * Discover tool schemas from a server with auto-start capability
+     * Uses cache (in-memory first, then disk) to avoid repeated restarts
+     * Auto-starts servers on first discovery (transparent to caller)
+     * Persists schemas to disk for faster discovery across daemon restarts
+     */
+    async discoverToolSchemas(serverName, config) {
+        // 1. Check in-memory cache first (fastest)
+        const memCached = this.toolSchemaCache.get(serverName);
+        if (memCached && Date.now() - memCached.timestamp < this.schemasCacheTTL) {
+            console.log(`[Discovery] Using in-memory cache for ${serverName} (${memCached.tools.length} tools, TTL: ${this.schemasCacheTTL}ms)`);
+            this.discoveredServers.add(serverName);
+            this.resetDiscoveryTimer(serverName); // v1.4.0: Start/reset expiration timer
+            // Trigger background refresh if nearing expiration
+            if (this.schemasBackgroundRefresh &&
+                Date.now() - memCached.timestamp > this.schemasCacheTTL * 0.8) {
+                this.refreshSchemaForServer(serverName).catch((error) => {
+                    console.warn(`[Discovery] Background refresh failed for ${serverName}:`, error);
+                });
+            }
+            // CRITICAL FIX: Ensure annotations are present in cached tools
+            // The cache should already have enriched tools, but verify
+            const hasAnnotations = memCached.tools.length > 0 && memCached.tools[0].annotations;
+            if (!hasAnnotations) {
+                console.log(`[Discovery] Cache missing annotations for ${serverName}, enriching...`);
+                return this.enrichToolsWithAnnotations(serverName, memCached.tools);
+            }
+            return memCached.tools;
+        }
+        // 2. Check disk cache if memory miss (Phase 1: v1.3.9+)
+        if (this.schemaStore) {
+            try {
+                const diskSchemas = await this.schemaStore.loadFromDisk();
+                const diskCached = diskSchemas.get(serverName);
+                if (diskCached &&
+                    Date.now() - diskCached.timestamp < this.schemasCacheTTL) {
+                    console.log(`[Discovery] Using disk cache for ${serverName} (${diskCached.tools.length} tools)`);
+                    this.toolSchemaCache.set(serverName, diskCached);
+                    this.discoveredServers.add(serverName);
+                    this.resetDiscoveryTimer(serverName); // v1.4.0: Start/reset expiration timer
+                    // Trigger background refresh if nearing expiration
+                    if (this.schemasBackgroundRefresh &&
+                        Date.now() - diskCached.timestamp > this.schemasCacheTTL * 0.8) {
+                        this.refreshSchemaForServer(serverName).catch((error) => {
+                            console.warn(`[Discovery] Background refresh failed for ${serverName}:`, error);
+                        });
+                    }
+                    // CRITICAL FIX: Ensure annotations are present in disk cached tools
+                    const hasAnnotations = diskCached.tools.length > 0 && diskCached.tools[0].annotations;
+                    if (!hasAnnotations) {
+                        console.log(`[Discovery] Disk cache missing annotations for ${serverName}, enriching...`);
+                        return this.enrichToolsWithAnnotations(serverName, diskCached.tools);
+                    }
+                    return diskCached.tools;
+                }
+            }
+            catch (error) {
+                console.warn(`[Discovery] Failed to check disk cache for ${serverName}:`, error);
+                // Fall through to server startup
+            }
+        }
+        // 3. If server is already running, use its tools
+        if (this.isServerActive(serverName)) {
+            const tools = this.getServerTools(serverName);
+            console.log(`[Discovery] Using running server tools for ${serverName} (${tools.length} tools)`);
+            const schema = { tools, timestamp: Date.now() };
+            this.toolSchemaCache.set(serverName, schema);
+            this.discoveredServers.add(serverName);
+            this.resetDiscoveryTimer(serverName); // v1.4.0: Start/reset expiration timer
+            // Persist to disk asynchronously
+            if (this.schemaStore) {
+                this.schemaStore.saveToDisk(serverName, schema).catch((error) => {
+                    console.warn(`[Discovery] Failed to persist schema for ${serverName}:`, error);
+                });
+            }
+            return tools;
+        }
+        // 4. Auto-start server for discovery if not running (v1.3.8+)
+        console.log(`[Discovery] Auto-starting ${serverName} for schema discovery...`);
+        try {
+            await this.ensureServerStarted(serverName, config);
+            const tools = this.getServerTools(serverName);
+            console.log(`[Discovery] Discovered ${tools.length} tools from ${serverName}`);
+            const schema = { tools, timestamp: Date.now() };
+            this.toolSchemaCache.set(serverName, schema);
+            this.discoveredServers.add(serverName);
+            this.resetDiscoveryTimer(serverName); // v1.4.0: Start/reset expiration timer
+            // Persist to disk asynchronously (Phase 1: v1.3.9+)
+            if (this.schemaStore) {
+                this.schemaStore.saveToDisk(serverName, schema).catch((error) => {
+                    console.warn(`[Discovery] Failed to persist schema for ${serverName}:`, error);
+                });
+            }
+            return tools;
+        }
+        catch (error) {
+            console.error(`[Discovery] Failed to auto-start and discover ${serverName}:`, error);
+            throw new Error(`Server ${serverName} not found and failed to auto-start. Details: ${error instanceof Error ? error.message : String(error)}`);
+        }
+    }
+    /**
+     * Refresh schema for a specific server
+     * Used by discovery to keep schemas fresh
+     */
+    async refreshSchemaForServer(serverName) {
+        if (!this.isServerActive(serverName)) {
+            // Server not running, skip refresh
+            return;
+        }
+        try {
+            const process = this.getProcess(serverName);
+            if (!process)
+                return;
+            const tools = await this.fetchToolsFromProcess(process, serverName);
+            const schema = { tools, timestamp: Date.now() };
+            // Update cache
+            this.toolSchemaCache.set(serverName, schema);
+            // Persist to disk
+            if (this.schemaStore) {
+                await this.schemaStore.saveToDisk(serverName, schema);
+            }
+            console.log(`[Discovery] Refreshed schema for ${serverName}`);
+        }
+        catch (error) {
+            console.warn(`[Discovery] Failed to refresh schema for ${serverName}:`, error);
+        }
+    }
+    /**
+     * Ensure server is started, auto-starting if needed
+     * Used when direct tool call happens and server isn't running
+     */
+    async ensureServerStarted(serverName, config) {
+        // Check circuit breaker before attempting startup
+        const breaker = this.circuitBreakerManager.getBreaker(serverName);
+        if (!breaker.canExecute()) {
+            const metrics = breaker.getMetrics();
+            const timeUntilReset = metrics.lastFailureTime
+                ? Math.max(0, 30000 - (Date.now() - metrics.lastFailureTime))
+                : 0;
+            throw new Error(`Circuit breaker is OPEN for ${serverName}. ` +
+                `Server has failed ${metrics.failures} consecutive times. ` +
+                `Retry in ${Math.ceil(timeUntilReset / 1000)}s.`);
+        }
+        // v1.1.8: Check if startup already in progress (mutex pattern)
+        if (this.startupMutex.has(serverName)) {
+            const mutex = this.startupMutex.get(serverName);
+            mutex.callerCount++;
+            console.log(`[Auto-Start] ${serverName} startup in progress, waiting... (caller ${mutex.callerCount})`);
+            return mutex.promise;
+        }
+        // v1.1.8: Check if already started
+        if (this.processes.has(serverName) || this.httpClients.has(serverName)) {
+            this.discoveredServers.add(serverName);
+            // v1.1.56: Always ensure server is in activeServers if process exists
+            if (!this.activeServers.has(serverName)) {
+                console.warn(`[Auto-Start] ${serverName} has process but not in activeServers. Recovering state...`);
+                // Try to load from cache first
+                const cached = this.toolSchemaCache.get(serverName);
+                if (cached?.tools && cached.tools.length > 0) {
+                    const process = this.processes.get(serverName);
+                    this.setServerTools(serverName, cached.tools, process);
+                    console.log(`[Auto-Start] Recovered ${serverName} from cache: ${cached.tools.length} tools`);
+                }
+                else {
+                    // No cache - fetch tools from running process
+                    const process = this.processes.get(serverName);
+                    if (process && !process.killed) {
+                        console.log(`[Auto-Start] No cache for ${serverName}, fetching tools from process...`);
+                        try {
+                            const tools = await this.fetchToolsFromProcess(process, serverName);
+                            this.setServerTools(serverName, tools, process);
+                            console.log(`[Auto-Start] Recovered ${serverName}: fetched ${tools.length} tools`);
+                        }
+                        catch (error) {
+                            console.error(`[Auto-Start] Failed to fetch tools for ${serverName}:`, error);
+                            // Process exists but can't get tools - kill it and restart
+                            console.warn(`[Auto-Start] Killing corrupted process for ${serverName} and restarting...`);
+                            await this.stopServer(serverName);
+                            await this.startServer(config);
+                        }
+                    }
+                    else {
+                        console.log(`[Auto-Start] HTTP server ${serverName} exists, using cached schema`);
+                    }
+                }
+            }
+            return;
+        }
+        // v1.1.8: Create mutex entry before starting
+        const startPromise = this.performServerStartup(serverName, config);
+        this.startupMutex.set(serverName, {
+            promise: startPromise,
+            startTime: Date.now(),
+            callerCount: 1,
+        });
+        // v1.1.27: Enhanced mutex cleanup with error logging
+        startPromise
+            .catch((error) => {
+            console.error(`[Auto-Start] ${serverName} startup failed:`, error instanceof Error ? error.message : String(error));
+        })
+            .finally(() => {
+            const mutex = this.startupMutex.get(serverName);
+            if (mutex) {
+                const duration = Date.now() - mutex.startTime;
+                console.log(`[Auto-Start] ${serverName} completed in ${duration}ms (${mutex.callerCount} waiters)`);
+                this.startupMutex.delete(serverName);
+            }
+        });
+        return startPromise;
+    }
+    /**
+     * v1.1.8: Actual server startup logic (called only by first concurrent request)
+     * Other concurrent requests wait for this promise via mutex
+     */
+    async performServerStartup(serverName, config) {
+        const breaker = this.circuitBreakerManager.getBreaker(serverName);
+        try {
+            if (this.isServerActive(serverName)) {
+                this.discoveredServers.add(serverName);
+                breaker.recordSuccess();
+                return;
+            }
+            console.log(`[Auto-Start] Starting ${serverName} for first tool call...`);
+            await this.startServer(config);
+            // Use cached schemas if available, otherwise fetch
+            if (this.toolSchemaCache.has(serverName)) {
+                const cached = this.toolSchemaCache.get(serverName);
+                // Even with cached schemas, wait for server initialization to complete
+                const process = this.getProcess(serverName);
+                if (process) {
+                    try {
+                        await this.waitForInitialization(process, serverName);
+                    }
+                    catch (error) {
+                        console.error(`[Auto-Start] Initialization failed for ${serverName}:`, error);
+                        breaker.recordFailure();
+                        throw error;
+                    }
+                }
+                this.setServerTools(serverName, cached.tools);
+                this.discoveredServers.add(serverName);
+                console.log(`[Auto-Start] Using cached schemas for ${serverName} (${cached.tools.length} tools)`);
+            }
+            else {
+                let tools = [];
+                const isHttpServer = this.httpClients.has(serverName);
+                if (isHttpServer) {
+                    const client = this.httpClients.get(serverName);
+                    try {
+                        const response = await client.call("tools/list", {});
+                        if (response.result &&
+                            typeof response.result === "object" &&
+                            "tools" in response.result) {
+                            tools = response.result.tools;
+                        }
+                    }
+                    catch (error) {
+                        console.warn(`[Auto-Start] Failed to fetch tools from HTTP server ${serverName}:`, error);
+                        breaker.recordFailure();
+                        throw error;
+                    }
+                }
+                else {
+                    tools = await this.fetchToolsFromProcess(this.getProcess(serverName), serverName);
+                }
+                this.setServerTools(serverName, tools);
+                const schema = { tools, timestamp: Date.now() };
+                this.toolSchemaCache.set(serverName, schema);
+                this.discoveredServers.add(serverName);
+                // Persist to disk asynchronously
+                if (this.schemaStore) {
+                    this.schemaStore.saveToDisk(serverName, schema).catch((error) => {
+                        console.warn(`[Auto-Start] Failed to persist schema for ${serverName}:`, error);
+                    });
+                }
+                console.log(`[Auto-Start] Fetched schemas from ${serverName} (${tools.length} tools)`);
+            }
+            this.setupServerResponseRouter(serverName);
+            // Record success for circuit breaker
+            breaker.recordSuccess();
+        }
+        catch (error) {
+            // Record failure for circuit breaker
+            breaker.recordFailure();
+            throw error;
+        }
+    }
+    /**
+     * Get discovered servers list
+     */
+    getDiscoveredServers() {
+        return Array.from(this.discoveredServers);
+    }
+    /**
+     * Get server tools from cache (if discovered)
+     */
+    getServerToolsFromCache(serverName) {
+        const cached = this.toolSchemaCache.get(serverName);
+        if (cached) {
+            this.discoveredServers.add(serverName);
+            return cached.tools;
+        }
+        return null;
+    }
+    /**
+     * Get circuit breaker metrics for a specific server
+     *
+     * @param serverName - Name of the server
+     * @returns Circuit breaker metrics or null if server not found
+     */
+    getCircuitBreakerMetrics(serverName) {
+        const breaker = this.circuitBreakerManager.getAllBreakers().get(serverName);
+        if (breaker) {
+            return breaker.getMetrics();
+        }
+        return null;
+    }
+    /**
+     * Get circuit breaker metrics for all servers
+     *
+     * @returns Array of metrics for all servers with circuit breakers
+     */
+    getAllCircuitBreakerMetrics() {
+        return this.circuitBreakerManager.getAllMetrics();
+    }
+    /**
+     * Manually reset circuit breaker for a server
+     *
+     * @param serverName - Name of the server
+     */
+    resetCircuitBreaker(serverName) {
+        this.circuitBreakerManager.reset(serverName);
+    }
+    /**
+     * Reset all circuit breakers
+     */
+    resetAllCircuitBreakers() {
+        this.circuitBreakerManager.resetAll();
+    }
+    /**
+     * Set callback for tools/list changes (v1.4.0)
+     * Called when discovery expires
+     */
+    setToolsListChangedCallback(callback) {
+        this.onToolsListChanged = callback;
+    }
+    /**
+     * v1.3.72: Set server list provider for proactive schema caching
+     * This allows background refresh to discover all servers, not just running ones
+     */
+    setServerListProvider(provider) {
+        this.serverListProvider = provider;
+        console.log("[ServerManager] Server list provider set for proactive schema caching");
+    }
+    /**
+     * Phase 2: Set config loader for tool safety classification
+     */
+    setConfigLoader(configLoader) {
+        this.configLoader = configLoader;
+    }
+    /**
+     * Phase 2: Classify tool safety level: 'safe' (auto-approve) or 'risky' (requires confirmation)
+     * Dynamic classification based on config rules
+     *
+     * @param serverName - Server name (e.g., "memory", "jira-basic-auth")
+     * @param toolName - Tool name (e.g., "create_entities", "search_issues")
+     * @returns Object with safety classification and reason
+     */
+    classifyToolSafety(serverName, toolName, toolArguments) {
+        if (!this.configLoader) {
+            console.log(`[SafetyClassify] No configLoader set, defaulting to risky for ${serverName}:${toolName}`);
+            return {
+                safety: "risky",
+                reason: "No safety rules configured (default: risky)",
+            };
+        }
+        const rules = this.configLoader.getToolSafetyRules();
+        const fullName = `${serverName}:${toolName}`;
+        // Debug logging
+        console.log(`[SafetyClassify] Checking ${fullName}${toolArguments ? " (with arguments)" : ""}`);
+        console.log(`[SafetyClassify] safeToolOverrides:`, rules.safeToolOverrides);
+        // v1.3.x: Check server-level safety first (highest priority)
+        const serverConfig = this.configLoader.getServer(serverName);
+        if (serverConfig) {
+            const serverSafety = serverConfig.safety;
+            if (serverSafety === "safe") {
+                console.log(`[SafetyClassify] ${fullName} => SAFE (server-level: ${serverName} is trusted)`);
+                return {
+                    safety: "safe",
+                    reason: `Server '${serverName}' is configured as trusted (all tools safe)`,
+                };
+            }
+            else if (serverSafety === "risky") {
+                console.log(`[SafetyClassify] ${fullName} => RISKY (server-level: ${serverName} is untrusted)`);
+                return {
+                    safety: "risky",
+                    reason: `Server '${serverName}' is configured as untrusted (all tools risky)`,
+                };
+            }
+            // undefined or 'default' falls through to tool-level classification
+        }
+        // Check explicit risky overrides first (highest priority)
+        if (rules.riskyToolOverrides?.some((pattern) => {
+            // Escape special regex chars, then replace * with .* for wildcard support
+            const escapedPattern = "^" +
+                pattern.replace(/[.+?^${}()|[\]\\]/g, "\\$&").replace(/\*/g, ".*") +
+                "$";
+            const regex = new RegExp(escapedPattern);
+            const matches = regex.test(fullName);
+            if (matches) {
+                console.log(`[SafetyClassify] ${fullName} matched riskyToolOverride: ${pattern}`);
+            }
+            return matches;
+        })) {
+            console.log(`[SafetyClassify] ${fullName} => RISKY (riskyToolOverrides)`);
+            return { safety: "risky", reason: "Matches risky tool override pattern" };
+        }
+        // Check explicit safe overrides (BEFORE argument inspection)
+        const safeOverrideMatch = rules.safeToolOverrides?.some((pattern) => {
+            // Escape special regex chars, then replace * with .* for wildcard support
+            const escapedPattern = "^" +
+                pattern.replace(/[.+?^${}()|[\]\\]/g, "\\$&").replace(/\*/g, ".*") +
+                "$";
+            const regex = new RegExp(escapedPattern);
+            const matches = regex.test(fullName);
+            if (matches) {
+                console.log(`[SafetyClassify] ${fullName} matched safeToolOverride: ${pattern} (regex: ${regex})`);
+            }
+            return matches;
+        });
+        if (safeOverrideMatch) {
+            console.log(`[SafetyClassify] ${fullName} => SAFE (safeToolOverrides)`);
+            return { safety: "safe", reason: "Matches safe tool override pattern" };
+        }
+        // v1.1.29: Check argument-level inspection rules
+        if (toolArguments && rules.argumentInspectionRules) {
+            const inspectionResult = this.inspectToolArguments(fullName, toolArguments, rules.argumentInspectionRules);
+            if (inspectionResult) {
+                console.log(`[SafetyClassify] ${fullName} => ${inspectionResult.safety.toUpperCase()} (argument inspection: ${inspectionResult.reason})`);
+                return inspectionResult;
+            }
+        }
+        // Check risky patterns (if matches, it's risky)
+        if (rules.riskyPatterns?.some((pattern) => {
+            const regex = new RegExp(pattern, "i");
+            const matches = regex.test(toolName);
+            if (matches) {
+                console.log(`[SafetyClassify] ${fullName} matched riskyPattern: ${pattern}`);
+            }
+            return matches;
+        })) {
+            console.log(`[SafetyClassify] ${fullName} => RISKY (riskyPatterns)`);
+            return {
+                safety: "risky",
+                reason: "Tool name matches risky pattern (create, update, delete, etc.)",
+            };
+        }
+        // Check safe patterns (if matches, it's safe)
+        if (rules.safePatterns?.some((pattern) => {
+            const regex = new RegExp(pattern, "i");
+            return regex.test(toolName);
+        })) {
+            console.log(`[SafetyClassify] ${fullName} => SAFE (safePatterns)`);
+            return {
+                safety: "safe",
+                reason: "Tool name matches safe pattern (search, get, list, etc.)",
+            };
+        }
+        // v1.1.50: Analyze tool description for safety indicators before defaulting to risky
+        const toolSchema = this.getToolSchema(serverName, toolName);
+        if (toolSchema?.description) {
+            const descResult = this.classifyByDescription(fullName, toolSchema.description);
+            if (descResult) {
+                return descResult;
+            }
+        }
+        // Default to risky (fail-safe: require confirmation for unknown tools)
+        console.log(`[SafetyClassify] ${fullName} => RISKY (default)`);
+        return {
+            safety: "risky",
+            reason: "No matching safety pattern (default: risky)",
+        };
+    }
+    /**
+     * v1.1.50: Classify tool safety based on description analysis
+     * Analyzes tool description for keywords that indicate read-only vs modifying operations
+     *
+     * @param fullName - Full tool name (server:tool)
+     * @param description - Tool description to analyze
+     * @returns Safety classification or null if inconclusive
+     */
+    classifyByDescription(fullName, description) {
+        const desc = description.toLowerCase();
+        // Keywords that strongly indicate read-only operations
+        const safeKeywords = [
+            /^(gets?|retrieves?|returns?|shows?|displays?|lists?|searches?|fetches?|reads?|views?)\b/,
+            /\b(read[- ]?only|readonly|non[- ]?destructive)\b/,
+            /\breturns?\s+(a\s+)?(list|array|object|string|number|boolean|information|data|details|status|result)/i,
+            /\b(documentation|help|info|metadata|schema|version)\b/,
+        ];
+        // Keywords that strongly indicate modifying operations
+        const riskyKeywords = [
+            /^(creates?|deletes?|removes?|updates?|modifies?|changes?|sets?|writes?|adds?|inserts?|drops?|alters?|executes?|runs?|sends?|posts?|puts?)\b/,
+            /\b(will\s+)?(create|delete|remove|update|modify|change|set|write|add|insert|drop|alter|execute|run|send|post|put)\s+(a\s+)?(new\s+)?/i,
+            /\b(destructive|irreversible|permanent)\b/,
+        ];
+        // Check for safe indicators
+        for (const pattern of safeKeywords) {
+            if (pattern.test(desc)) {
+                console.log(`[SafetyClassify] ${fullName} => SAFE (description analysis: matches "${pattern}")`);
+                return {
+                    safety: "safe",
+                    reason: `Description indicates read-only operation`,
+                };
+            }
+        }
+        // Check for risky indicators
+        for (const pattern of riskyKeywords) {
+            if (pattern.test(desc)) {
+                console.log(`[SafetyClassify] ${fullName} => RISKY (description analysis: matches "${pattern}")`);
+                return {
+                    safety: "risky",
+                    reason: `Description indicates modifying operation`,
+                };
+            }
+        }
+        // Inconclusive - let caller handle default
+        console.log(`[SafetyClassify] ${fullName} description analysis inconclusive`);
+        return null;
+    }
+    /**
+     * v1.3.x: Resolve nested path in object (e.g., "params.path" -> obj.params.path)
+     *
+     * @param obj - Object to extract value from
+     * @param path - Dot-separated path (e.g., "params.path", "body.query.bool")
+     * @returns Value at path or undefined if not found
+     */
+    resolveNestedPath(obj, path) {
+        const parts = path.split(".");
+        let current = obj;
+        for (const part of parts) {
+            if (current === null || current === undefined) {
+                return undefined;
+            }
+            if (typeof current !== "object") {
+                return undefined;
+            }
+            current = current[part];
+        }
+        return current;
+    }
+    /**
+     * v1.1.29: Inspect tool arguments for command-level safety classification
+     * v1.3.x: Enhanced to support nested paths (e.g., "params.path")
+     *
+     * @param fullToolName - Full tool name (e.g., "ssh:runRemoteCommand")
+     * @param toolArguments - Arguments passed to the tool
+     * @param inspectionRules - Argument inspection rules from config
+     * @returns Safety classification result or null if no matching rule
+     */
+    inspectToolArguments(fullToolName, toolArguments, inspectionRules) {
+        // v1.1.55: Find matching inspection rule with wildcard support
+        // Supports patterns like "metabase*:execute" to match "metabase:execute", "metabase-foo:execute"
+        const rule = inspectionRules.find((r) => {
+            if (r.tool === fullToolName)
+                return true; // Exact match
+            // Convert wildcard pattern to regex (supports * and ? wildcards)
+            if (r.tool.includes("*") || r.tool.includes("?")) {
+                const regexPattern = r.tool
+                    .replace(/[.+^${}()|[\]\\]/g, "\\$&") // Escape regex special chars except * and ?
+                    .replace(/\*/g, ".*") // * = any characters
+                    .replace(/\?/g, "."); // ? = single character
+                const regex = new RegExp(`^${regexPattern}$`, "i");
+                return regex.test(fullToolName);
+            }
+            return false;
+        });
+        if (!rule) {
+            return null; // No inspection rule for this tool
+        }
+        // v1.3.x: Extract the argument field value with nested path support
+        // e.g., "command" for top-level, "params.path" for nested
+        const argumentValue = rule.argumentField.includes(".")
+            ? this.resolveNestedPath(toolArguments, rule.argumentField)
+            : toolArguments[rule.argumentField];
+        if (!argumentValue) {
+            // v1.1.55: If field is optional, skip inspection (return null) instead of marking risky
+            // This allows tools with multiple modes (SQL vs card_id) to fall through to other rules
+            if (rule.optionalField) {
+                console.log(`[ArgumentInspection] ${fullToolName}: Optional field "${rule.argumentField}" missing, skipping inspection`);
+                return null;
+            }
+            console.log(`[ArgumentInspection] ${fullToolName}: Missing argument field "${rule.argumentField}"`);
+            return {
+                safety: "risky",
+                reason: `Missing required argument field for inspection: ${rule.argumentField}`,
+            };
+        }
+        // Handle array of commands (for batch operations)
+        const commands = Array.isArray(argumentValue)
+            ? argumentValue
+            : [argumentValue];
+        for (const cmd of commands) {
+            const commandStr = String(cmd);
+            console.log(`[ArgumentInspection] ${fullToolName}: Inspecting command: "${commandStr}"`);
+            // Check risky command patterns first (highest priority)
+            if (rule.riskyCommandPatterns) {
+                for (const pattern of rule.riskyCommandPatterns) {
+                    const regex = new RegExp(pattern, "i");
+                    if (regex.test(commandStr)) {
+                        console.log(`[ArgumentInspection] ${fullToolName}: Command matched risky pattern: ${pattern}`);
+                        return {
+                            safety: "risky",
+                            reason: `Command matches risky pattern: ${pattern}`,
+                        };
+                    }
+                }
+            }
+            // Check safe command patterns
+            if (rule.safeCommandPatterns) {
+                let matchedSafePattern = false;
+                for (const pattern of rule.safeCommandPatterns) {
+                    const regex = new RegExp(pattern, "i");
+                    if (regex.test(commandStr)) {
+                        console.log(`[ArgumentInspection] ${fullToolName}: Command matched safe pattern: ${pattern}`);
+                        matchedSafePattern = true;
+                        break;
+                    }
+                }
+                if (matchedSafePattern) {
+                    continue; // This command is safe, check next
+                }
+                else if (rule.whitelistMode) {
+                    // Whitelist mode: reject if not in safe patterns
+                    console.log(`[ArgumentInspection] ${fullToolName}: Command NOT in whitelist (whitelist mode enabled)`);
+                    return {
+                        safety: "risky",
+                        reason: "Command not in safe command whitelist",
+                    };
+                }
+                else {
+                    // Blacklist mode: no match in safe or risky patterns, default to risky
+                    console.log(`[ArgumentInspection] ${fullToolName}: Command not matched by any pattern (defaulting to risky)`);
+                    return {
+                        safety: "risky",
+                        reason: "Command does not match any known safe pattern",
+                    };
+                }
+            }
+        }
+        // All commands passed inspection
+        console.log(`[ArgumentInspection] ${fullToolName}: All commands safe`);
+        return {
+            safety: "safe",
+            reason: "All commands match safe patterns",
+        };
+    }
+    /**
+     * Phase 2: Enrich tools with safety annotations
+     * Adds annotations field to each tool with safety classification
+     *
+     * @param serverName - Server name
+     * @param tools - Array of tools from server
+     * @returns Tools enriched with annotations
+     */
+    enrichToolsWithAnnotations(serverName, tools) {
+        return tools.map((tool) => {
+            const classification = this.classifyToolSafety(serverName, tool.name);
+            return {
+                ...tool,
+                annotations: {
+                    safety: classification.safety,
+                    safetyReason: classification.reason,
+                    requiresConfirmation: classification.safety === "risky",
+                },
+            };
+        });
+    }
+    /**
+     * Check if server is discovered (v1.4.0)
+     */
+    isDiscovered(serverName) {
+        return this.discoveredServers.has(serverName);
+    }
+    /**
+     * Refresh discovery timer for active server (v1.4.0)
+     * Called on tool execution to keep active servers available
+     */
+    refreshDiscoveryTimer(serverName) {
+        if (this.discoveredServers.has(serverName)) {
+            this.resetDiscoveryTimer(serverName);
+        }
+    }
+    /**
+     * Reset/start discovery timer (v1.4.0 - private)
+     * @param serverName Server to reset timer for
+     */
+    resetDiscoveryTimer(serverName) {
+        // Clear existing timer
+        if (this.discoveryTimers.has(serverName)) {
+            clearTimeout(this.discoveryTimers.get(serverName));
+        }
+        // Don't set timers for base servers (never expire)
+        if (this.baseServers.includes(serverName)) {
+            return;
+        }
+        // Don't set timer if TTL is 0 (disabled)
+        if (this.discoveryTTL === 0) {
+            return;
+        }
+        // Start new timer
+        const timer = setTimeout(() => {
+            this.expireDiscoveredServer(serverName);
+        }, this.discoveryTTL);
+        this.discoveryTimers.set(serverName, timer);
+    }
+    /**
+     * Expire discovered server (v1.4.0 - private)
+     * Removes server from cache and notifies clients
+     */
+    expireDiscoveredServer(serverName) {
+        // Skip base servers (safety check)
+        if (this.baseServers.includes(serverName)) {
+            return;
+        }
+        // Skip if server has active requests (defer expiration)
+        const serverProcess = this.processes.get(serverName);
+        if (serverProcess && this.hasActiveRequests(serverProcess)) {
+            console.log(`[MetaLink] Deferring expiration of '${serverName}' (active requests)`);
+            this.resetDiscoveryTimer(serverName); // Try again in TTL period
+            return;
+        }
+        // Remove from cache
+        console.log(`[MetaLink] Expiring discovered server: ${serverName}`);
+        this.toolSchemaCache.delete(serverName);
+        this.discoveredServers.delete(serverName);
+        this.discoveryTimers.delete(serverName);
+        // Stop server process if not base server
+        if (this.processes.has(serverName)) {
+            this.stopServer(serverName).catch((err) => {
+                console.warn(`[MetaLink] Failed to stop expired server ${serverName}:`, err);
+            });
+        }
+        // Notify via callback (HTTP server will broadcast)
+        if (this.onToolsListChanged) {
+            this.onToolsListChanged();
+        }
+    }
+    /**
+     * Check if server has active requests (v1.4.0 - private)
+     * Simple heuristic: check if process started recently
+     */
+    hasActiveRequests(serverProcess) {
+        // Check if there are pending requests for this server
+        const serverName = Array.from(this.processes.entries()).find(([, proc]) => proc === serverProcess)?.[0];
+        if (serverName && this.pendingRequests.has(serverName)) {
+            const pending = this.pendingRequests.get(serverName);
+            if (pending && pending.size > 0) {
+                return true; // Has pending requests
+            }
+        }
+        // Fallback: check if process started recently (< gracefulShutdown timeout)
+        const processAge = Date.now() - (serverProcess.startTime || 0);
+        return processAge < this.timeouts.gracefulShutdown;
+    }
+    /**
+     * Validate tool schemas and log warnings/suggestions
+     * v1.4.0: Schema validation for improved schema quality
+     */
+    validateToolSchemas(tools, serverName) {
+        const validator = new SchemaValidator();
+        for (const tool of tools) {
+            const result = validator.validateToolSchema(tool);
+            // Log errors
+            if (result.errors.length > 0) {
+                console.error(`[SchemaValidator] ❌ Errors in ${serverName ? `${serverName}-` : ""}${tool.name}:`);
+                for (const error of result.errors) {
+                    console.error(`  • ${error}`);
+                }
+            }
+            // Log warnings
+            if (result.warnings.length > 0) {
+                console.warn(`[SchemaValidator] ⚠️  Warnings for ${serverName ? `${serverName}-` : ""}${tool.name}:`);
+                for (const warning of result.warnings) {
+                    console.warn(`  • ${warning.field}: ${warning.message}`);
+                }
+            }
+            // Log suggestions
+            if (result.suggestions && result.suggestions.length > 0) {
+                console.log(`[SchemaValidator] 💡 Suggestions for ${serverName ? `${serverName}-` : ""}${tool.name}:`);
+                for (const suggestion of result.suggestions) {
+                    console.log(`  • ${suggestion}`);
+                }
+            }
+            // Log inferred required parameters
+            if (result.inferredRequired && result.inferredRequired.length > 0) {
+                console.log(`[SchemaValidator] 🔍 Inferred required params for ${serverName ? `${serverName}-` : ""}${tool.name}: ${result.inferredRequired.join(", ")}`);
+            }
+        }
+    }
+    /**
+     * Cleanup all servers
+     */
+    async cleanup() {
+        // Clear all discovery timers (v1.4.0)
+        for (const timer of this.discoveryTimers.values()) {
+            clearTimeout(timer);
+        }
+        this.discoveryTimers.clear();
+        // Stop background refresh
+        if (this.backgroundRefreshInterval) {
+            clearInterval(this.backgroundRefreshInterval);
+            this.backgroundRefreshInterval = null;
+            console.log("[SchemaStore] Stopped background refresh");
+        }
+        // Cleanup circuit breakers
+        this.circuitBreakerManager.destroy();
+        console.log("[CircuitBreaker] Cleaned up all circuit breakers");
+        // Flush pending disk writes
+        if (this.schemaStore) {
+            try {
+                await this.schemaStore.flush();
+            }
+            catch (error) {
+                console.warn("[SchemaStore] Failed to flush during cleanup:", error);
+            }
+        }
+        const servers = Array.from(this.processes.keys());
+        for (const serverName of servers) {
+            try {
+                await this.stopServer(serverName);
+            }
+            catch (error) {
+                console.error(`Failed to stop server ${serverName}:`, error);
+            }
+        }
+        // Clear all health check intervals
+        for (const interval of this.healthCheckIntervals.values()) {
+            clearInterval(interval);
+        }
+        this.healthCheckIntervals.clear();
+        this.activeServers.clear();
+        // Clear all auto-restart timers
+        for (const restartInfo of this.restartAttempts.values()) {
+            if (restartInfo.restartTimer) {
+                clearTimeout(restartInfo.restartTimer);
+            }
+        }
+        this.restartAttempts.clear();
+    }
+    /**
+     * Calculate exponential backoff delay for restart attempts
+     */
+    calculateBackoffDelay(attemptNumber) {
+        const { baseDelay, maxDelay, backoffMultiplier } = this.autoRestartConfig;
+        const exponentialDelay = baseDelay * Math.pow(backoffMultiplier, attemptNumber);
+        return Math.min(exponentialDelay, maxDelay);
+    }
+    /**
+     * Schedule a server restart with exponential backoff
+     */
+    scheduleServerRestart(serverName) {
+        if (!this.autoRestartConfig.enabled) {
+            console.log(`[AutoRestart] Auto-restart disabled for ${serverName}`);
+            return;
+        }
+        // Get or initialize restart tracking
+        let restartInfo = this.restartAttempts.get(serverName);
+        if (!restartInfo) {
+            restartInfo = {
+                count: 0,
+                lastAttempt: 0,
+                nextRetryTime: 0,
+            };
+            this.restartAttempts.set(serverName, restartInfo);
+        }
+        // Check if we've exceeded max retries
+        if (restartInfo.count >= this.autoRestartConfig.maxRetries) {
+            console.error(`[AutoRestart] ${serverName} has failed ${restartInfo.count} times. ` +
+                `Maximum retry limit (${this.autoRestartConfig.maxRetries}) reached. ` +
+                `Manual intervention required.`);
+            this.emit("server:restart-limit-reached", {
+                serverName,
+                attemptCount: restartInfo.count,
+                maxRetries: this.autoRestartConfig.maxRetries,
+            });
+            return;
+        }
+        // Cancel any existing restart timer
+        if (restartInfo.restartTimer) {
+            clearTimeout(restartInfo.restartTimer);
+        }
+        // Calculate backoff delay
+        const delay = this.calculateBackoffDelay(restartInfo.count);
+        const nextRetryTime = Date.now() + delay;
+        console.log(`[AutoRestart] Scheduling restart attempt ${restartInfo.count + 1}/${this.autoRestartConfig.maxRetries} ` +
+            `for ${serverName} in ${delay}ms (${Math.round(delay / 1000)}s)`);
+        // Update restart tracking
+        restartInfo.count++;
+        restartInfo.nextRetryTime = nextRetryTime;
+        // Schedule the restart
+        restartInfo.restartTimer = setTimeout(async () => {
+            console.log(`[AutoRestart] Attempting restart ${restartInfo.count}/${this.autoRestartConfig.maxRetries} ` +
+                `for ${serverName}`);
+            restartInfo.lastAttempt = Date.now();
+            try {
+                // Attempt to restart the server
+                await this.attemptServerRestart(serverName);
+                // If successful, reset restart tracking
+                console.log(`[AutoRestart] Successfully restarted ${serverName}`);
+                this.resetRestartTracking(serverName);
+                this.emit("server:restart-success", {
+                    serverName,
+                    attemptCount: restartInfo.count,
+                });
+            }
+            catch (error) {
+                console.error(`[AutoRestart] Restart attempt ${restartInfo.count} failed for ${serverName}: ` +
+                    `${error instanceof Error ? error.message : String(error)}`);
+                this.emit("server:restart-failed", {
+                    serverName,
+                    attemptCount: restartInfo.count,
+                    error: error instanceof Error ? error.message : String(error),
+                });
+                // The server will crash again if restart failed, triggering another schedule
+            }
+        }, delay);
+        this.emit("server:restart-scheduled", {
+            serverName,
+            attemptNumber: restartInfo.count,
+            delayMs: delay,
+            nextRetryTime,
+        });
+    }
+    /**
+     * Attempt to restart a failed server
+     */
+    async attemptServerRestart(serverName) {
+        // Get server config - need to look it up from the server list provider
+        if (!this.serverListProvider) {
+            throw new Error("Server list provider not configured");
+        }
+        const allConfigs = this.serverListProvider();
+        const config = allConfigs.find((c) => c.name === serverName);
+        if (!config) {
+            throw new Error(`No configuration found for server ${serverName}`);
+        }
+        // Clean up old process/client
+        await this.stopServer(serverName);
+        // Wait a brief moment for cleanup
+        await new Promise((resolve) => setTimeout(resolve, 1000));
+        // Start the server fresh
+        await this.startServer(config);
+        // Verify it started successfully
+        const isRunning = this.isServerActive(serverName);
+        if (!isRunning) {
+            throw new Error(`Server ${serverName} failed to start`);
+        }
+    }
+    /**
+     * Reset restart tracking for a server (called after successful restart)
+     */
+    resetRestartTracking(serverName) {
+        const restartInfo = this.restartAttempts.get(serverName);
+        if (restartInfo?.restartTimer) {
+            clearTimeout(restartInfo.restartTimer);
+        }
+        this.restartAttempts.delete(serverName);
+        console.log(`[AutoRestart] Reset restart tracking for ${serverName}`);
+    }
+    /**
+     * Get restart status for a server (public API for monitoring)
+     */
+    getRestartStatus(serverName) {
+        const restartInfo = this.restartAttempts.get(serverName);
+        if (!restartInfo) {
+            return {
+                inProgress: false,
+                attemptCount: 0,
+                nextRetryTime: null,
+            };
+        }
+        return {
+            inProgress: true,
+            attemptCount: restartInfo.count,
+            nextRetryTime: restartInfo.nextRetryTime,
+        };
+    }
+    /**
+     * v1.1.27: Graceful shutdown - clean up all timers and stop all servers
+     * Call this method before process exit to prevent memory leaks and orphaned timers
+     */
+    async shutdown() {
+        console.log("[ServerManager] Initiating graceful shutdown...");
+        // 1. Clear discovery timers
+        for (const [serverName, timer] of this.discoveryTimers.entries()) {
+            clearTimeout(timer);
+            console.log(`[ServerManager] Cleared discovery timer for ${serverName}`);
+        }
+        this.discoveryTimers.clear();
+        // 2. Clear background refresh interval
+        if (this.backgroundRefreshInterval) {
+            clearInterval(this.backgroundRefreshInterval);
+            this.backgroundRefreshInterval = null;
+            console.log("[ServerManager] Cleared background refresh interval");
+        }
+        // 3. Clear all health check intervals
+        for (const [serverName, interval] of this.healthCheckIntervals.entries()) {
+            clearInterval(interval);
+            console.log(`[ServerManager] Cleared health check interval for ${serverName}`);
+        }
+        this.healthCheckIntervals.clear();
+        // 4. Clear restart timers
+        for (const [serverName, restartInfo] of this.restartAttempts.entries()) {
+            if (restartInfo.restartTimer) {
+                clearTimeout(restartInfo.restartTimer);
+                console.log(`[ServerManager] Cleared restart timer for ${serverName}`);
+            }
+        }
+        this.restartAttempts.clear();
+        // 5. Clear startup mutexes
+        this.startupMutex.clear();
+        // 6. Stop all servers gracefully
+        const serverNames = [...this.processes.keys(), ...this.httpClients.keys()];
+        console.log(`[ServerManager] Stopping ${serverNames.length} servers...`);
+        const stopPromises = serverNames.map(async (serverName) => {
+            try {
+                await this.stopServer(serverName);
+                console.log(`[ServerManager] Stopped server: ${serverName}`);
+            }
+            catch (error) {
+                console.error(`[ServerManager] Error stopping server ${serverName}:`, error);
+            }
+        });
+        await Promise.allSettled(stopPromises);
+        // 7. Clear remaining state
+        this.activeServers.clear();
+        this.discoveredServers.clear();
+        this.toolSchemaCache.clear();
+        this.schemaStabilityMetrics.clear();
+        this.failedDiscoveryAttempts.clear();
+        this.stdoutBuffers.clear();
+        this.stdoutListeners.clear();
+        this.pendingRequests.clear();
+        this.requestIdCounters.clear();
+        console.log("[ServerManager] Shutdown complete");
+    }
+}
+//# sourceMappingURL=manager.js.map