@jagilber-org/index-server 1.19.1

package/dist/server/registry.d.ts

@@ -0,0 +1,44 @@
+export type Handler<TParams = unknown> = (params: TParams) => Promise<unknown> | unknown;
+interface MetricRecord {
+    count: number;
+    totalMs: number;
+    maxMs: number;
+}
+/**
+ * Register a tool handler in the in-process registry, wrapping it with metrics,
+ * audit logging, correlation IDs, and optional proxy forwarding.
+ * @param name - Tool name used to route incoming requests
+ * @param fn - Handler function; may return a plain value or a Promise
+ */
+export declare function registerHandler<TParams = unknown>(name: string, fn: Handler<TParams>): void;
+/**
+ * Look up a registered (wrapped) handler by name.
+ * @param name - Tool name to look up
+ * @returns The wrapped handler, or `undefined` if not registered
+ */
+export declare function getHandler(name: string): Handler<unknown>;
+/**
+ * Return the raw (unwrapped) handler that always executes locally,
+ * bypassing any installed proxy. Used by HttpTransport so the leader
+ * never accidentally routes its own handler calls through a proxy.
+ * @param name - Tool name to look up
+ * @returns The raw unwrapped handler, or `undefined` if not registered
+ */
+export declare function getLocalHandler(name: string): Handler<unknown>;
+export declare function installHandlerProxy(fn: ((tool: string, params: unknown) => Promise<unknown>) | null): void;
+/**
+ * Return the currently installed proxy function, or `null` if no proxy is active.
+ * @returns The proxy function, or `null`
+ */
+export declare function getHandlerProxy(): ((tool: string, params: unknown) => Promise<unknown>) | null;
+/**
+ * Return a sorted list of all registered tool method names.
+ * @returns Array of method name strings in alphabetical order
+ */
+export declare function listRegisteredMethods(): string[];
+/**
+ * Return the raw per-tool metrics record map (count, totalMs, maxMs).
+ * @returns Reference to the live metrics map keyed by tool name
+ */
+export declare function getMetricsRaw(): Record<string, MetricRecord>;
+export {};

package/dist/server/registry.js

@@ -0,0 +1,236 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.registerHandler = registerHandler;
+exports.getHandler = getHandler;
+exports.getLocalHandler = getLocalHandler;
+exports.installHandlerProxy = installHandlerProxy;
+exports.getHandlerProxy = getHandlerProxy;
+exports.listRegisteredMethods = listRegisteredMethods;
+exports.getMetricsRaw = getMetricsRaw;
+// Lightweight in-process tool registry used exclusively by the SDK server path.
+// Replaces the prior custom JSON-RPC transport layer.
+const logger_1 = require("../services/logger");
+const responseEnvelope_1 = require("../services/responseEnvelope");
+const auditLog_1 = require("../services/auditLog");
+const runtimeConfig_1 = require("../config/runtimeConfig");
+// Dashboard metrics integration: bridge per-tool execution to global MetricsCollector
+// so the admin panel performance & tool counters reflect live activity. Previously the
+// dashboard showed zeros because recordToolCall was never invoked along the runtime path.
+const MetricsCollector_js_1 = require("../dashboard/server/MetricsCollector.js");
+const handlers = {};
+// Raw (unwrapped) handlers that always execute locally - never go through proxy.
+// Used by HttpTransport so the leader always runs handlers locally even when
+// a proxy is installed in this process (e.g., same-process test scenarios).
+const localHandlers = {};
+const metrics = {};
+function recordMetric(name, ms) {
+    let rec = metrics[name];
+    if (!rec) {
+        rec = { count: 0, totalMs: 0, maxMs: 0 };
+        metrics[name] = rec;
+    }
+    rec.count++;
+    rec.totalMs += ms;
+    if (ms > rec.maxMs)
+        rec.maxMs = ms;
+}
+/**
+ * Register a tool handler in the in-process registry, wrapping it with metrics,
+ * audit logging, correlation IDs, and optional proxy forwarding.
+ * @param name - Tool name used to route incoming requests
+ * @param fn - Handler function; may return a plain value or a Promise
+ */
+function registerHandler(name, fn) {
+    // Always log tool lifecycle events (previously gated by INDEX_SERVER_LOG_TOOLS)
+    // Lazily resolve singleton (avoid throwing if dashboard disabled – metrics collector module
+    // still exports a singleton even when dashboard not started).
+    const collector = (() => { try {
+        return (0, MetricsCollector_js_1.getMetricsCollector)();
+    }
+    catch {
+        return null;
+    } })();
+    const wrapped = async (params) => {
+        const corr = (0, logger_1.newCorrelationId)();
+        // If a proxy is installed (follower mode), forward to leader instead of running locally
+        if (proxyFn) {
+            try {
+                (0, logger_1.log)('INFO', `[registry] → ${name} (proxy)`, { tool: name, correlationId: corr });
+            }
+            catch { /* ignore */ }
+            const startNs = typeof process.hrtime === 'function' ? process.hrtime.bigint() : BigInt(Date.now()) * 1000000n;
+            try {
+                const result = await proxyFn(name, params);
+                const endNs = typeof process.hrtime === 'function' ? process.hrtime.bigint() : BigInt(Date.now()) * 1000000n;
+                const ms = Number(endNs - startNs) / 1_000_000;
+                recordMetric(name, ms);
+                try {
+                    collector?.recordToolCall(name, true, ms);
+                }
+                catch { /* ignore */ }
+                try {
+                    (0, logger_1.log)('INFO', `[registry] ← ${name} (proxy)`, { tool: name, correlationId: corr, ms });
+                }
+                catch { /* ignore */ }
+                return result;
+            }
+            catch (e) {
+                const endNs = typeof process.hrtime === 'function' ? process.hrtime.bigint() : BigInt(Date.now()) * 1000000n;
+                const ms = Number(endNs - startNs) / 1_000_000;
+                recordMetric(name, ms);
+                try {
+                    collector?.recordToolCall(name, false, ms, 'proxy_error');
+                }
+                catch { /* ignore */ }
+                try {
+                    (0, logger_1.log)('ERROR', `[registry] Tool proxy error: ${name}`, { tool: name, correlationId: corr, detail: e instanceof Error ? e.stack : String(e) });
+                }
+                catch { /* ignore */ }
+                throw e;
+            }
+        }
+        const startNs = typeof process.hrtime === 'function' ? process.hrtime.bigint() : BigInt(Date.now()) * 1000000n;
+        const timingEnabled = process.env.INDEX_SERVER_ADD_TIMING === '1' || (0, runtimeConfig_1.getRuntimeConfig)().mutation.dispatcherTiming;
+        let phaseMarks;
+        if (timingEnabled) {
+            phaseMarks = [{ p: 'start', t: Date.now() }];
+        }
+        try {
+            (0, logger_1.log)('INFO', `[registry] → ${name}`, { tool: name, correlationId: corr });
+        }
+        catch { /* logging should not break */ }
+        let success = false;
+        let errorType;
+        try {
+            const result = await (0, auditLog_1.runWithCorrelation)(corr, () => Promise.resolve(fn(params)));
+            if (timingEnabled && phaseMarks) {
+                phaseMarks.push({ p: 'afterFn', t: Date.now() });
+            }
+            success = true;
+            const wrappedResp = (0, responseEnvelope_1.wrapResponse)(result);
+            if (timingEnabled) {
+                try {
+                    const endTs = Date.now();
+                    phaseMarks.push({ p: 'endPreWrap', t: endTs });
+                    const phases = phaseMarks;
+                    wrappedResp.__timing = { tool: name, phases };
+                }
+                catch { /* ignore timing embed errors */ }
+            }
+            return wrappedResp;
+        }
+        catch (e) {
+            try {
+                (0, logger_1.log)('ERROR', `[registry] Tool error: ${name}`, { tool: name, correlationId: corr, detail: e instanceof Error ? e.stack : String(e) });
+            }
+            catch { /* ignore */ }
+            // Best-effort classification for dashboard error breakdown
+            try {
+                const errObj = e;
+                // Narrow progressively without casting to any to satisfy eslint no-explicit-any rule.
+                if (typeof errObj === 'object' && errObj !== null) {
+                    const maybeCode = errObj.code;
+                    if (Number.isSafeInteger(maybeCode)) {
+                        errorType = `code_${maybeCode}`;
+                    }
+                    else {
+                        const maybeData = errObj.data;
+                        if (typeof maybeData === 'object' && maybeData !== null && typeof maybeData.reason === 'string') {
+                            errorType = String(maybeData.reason);
+                        }
+                        else if (typeof errObj.reason === 'string') {
+                            errorType = String(errObj.reason);
+                        }
+                        else {
+                            errorType = 'error';
+                        }
+                    }
+                }
+                else {
+                    errorType = 'error';
+                }
+            }
+            catch { /* ignore classification errors */ }
+            throw e;
+        }
+        finally {
+            const endNs = typeof process.hrtime === 'function' ? process.hrtime.bigint() : BigInt(Date.now()) * 1000000n;
+            const ms = Number(endNs - startNs) / 1_000_000;
+            recordMetric(name, ms);
+            if (timingEnabled && phaseMarks) {
+                try {
+                    phaseMarks.push({ p: 'finally', t: Date.now() });
+                }
+                catch { /* ignore */ }
+            }
+            // Feed global dashboard metrics (safe no-op if collector absent). This enables:
+            //  - requestsPerMinute (rolling window)
+            //  - successRate / errorRate
+            //  - per-tool call counts & avg response time
+            try {
+                collector?.recordToolCall(name, success, ms, success ? undefined : errorType);
+            }
+            catch { /* never block tool path */ }
+            try {
+                (0, auditLog_1.logToolAudit)(name, success, ms, corr, success ? undefined : errorType);
+            }
+            catch { /* never block tool path */ }
+            try {
+                (0, logger_1.log)('INFO', `[registry] ← ${name}`, { tool: name, correlationId: corr, ms });
+            }
+            catch { /* ignore */ }
+        }
+    };
+    handlers[name] = wrapped;
+    localHandlers[name] = fn;
+}
+/**
+ * Look up a registered (wrapped) handler by name.
+ * @param name - Tool name to look up
+ * @returns The wrapped handler, or `undefined` if not registered
+ */
+function getHandler(name) {
+    return handlers[name];
+}
+/**
+ * Return the raw (unwrapped) handler that always executes locally,
+ * bypassing any installed proxy. Used by HttpTransport so the leader
+ * never accidentally routes its own handler calls through a proxy.
+ * @param name - Tool name to look up
+ * @returns The raw unwrapped handler, or `undefined` if not registered
+ */
+function getLocalHandler(name) {
+    return localHandlers[name];
+}
+/**
+ * Install a proxy function that intercepts all handler calls.
+ * Used by follower instances to forward tool calls to the leader.
+ * The proxy receives (toolName, params) and returns the result.
+ * Pass null to remove the proxy (e.g., on promotion to leader).
+ * @param fn - Proxy function to install, or `null` to remove the current proxy
+ */
+let proxyFn = null;
+function installHandlerProxy(fn) {
+    proxyFn = fn;
+}
+/**
+ * Return the currently installed proxy function, or `null` if no proxy is active.
+ * @returns The proxy function, or `null`
+ */
+function getHandlerProxy() {
+    return proxyFn;
+}
+/**
+ * Return a sorted list of all registered tool method names.
+ * @returns Array of method name strings in alphabetical order
+ */
+function listRegisteredMethods() {
+    return Object.keys(handlers).sort();
+}
+/**
+ * Return the raw per-tool metrics record map (count, totalMs, maxMs).
+ * @returns Reference to the live metrics map keyed by tool name
+ */
+function getMetricsRaw() {
+    return metrics;
+}

package/dist/server/sdkServer.d.ts

@@ -0,0 +1,8 @@
+import '../services/toolHandlers';
+/**
+ * Create and configure an MCP SDK server instance with the full tool registry.
+ * @param ServerClass - The MCP SDK Server constructor (loaded dynamically to avoid ESM/CJS conflicts)
+ * @returns Configured SDK server instance with all tool handlers registered
+ */
+export declare function createSdkServer(ServerClass: any): any;
+export declare function startSdkServer(): Promise<void>;

package/dist/server/sdkServer.js

@@ -0,0 +1,299 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.createSdkServer = createSdkServer;
+exports.startSdkServer = startSdkServer;
+/* eslint-disable @typescript-eslint/no-explicit-any */
+/**
+ * SDK-based MCP server bootstrap (dynamic require variant to work under CommonJS build).
+ * Uses the published dist/ subpath exports without relying on TS ESM moduleResolution.
+ *
+ * Orchestrates server creation and startup, delegating handshake/protocol logic to
+ * handshakeManager.ts and transport/dispatcher setup to transportFactory.ts.
+ */
+const fs_1 = __importDefault(require("fs"));
+const path_1 = __importDefault(require("path"));
+const toolRegistry_1 = require("../services/toolRegistry");
+require("../services/toolHandlers");
+const registry_1 = require("./registry");
+const zod_1 = require("zod");
+const runtimeConfig_1 = require("../config/runtimeConfig");
+const handshakeManager_1 = require("./handshakeManager");
+const transportFactory_1 = require("./transportFactory");
+// ESM dynamic import used below for SDK modules.
+// We'll lazy-load ESM exports via dynamic import when starting.
+let StdioServerTransport;
+/**
+ * Create and configure an MCP SDK server instance with the full tool registry.
+ * @param ServerClass - The MCP SDK Server constructor (loaded dynamically to avoid ESM/CJS conflicts)
+ * @returns Configured SDK server instance with all tool handlers registered
+ */
+function createSdkServer(ServerClass) {
+    // Derive version from package.json (no artificial suffix so clients see real semantic version)
+    let version = '0.0.0';
+    const pkgCandidates = [
+        path_1.default.join(process.cwd(), 'package.json'),
+        path_1.default.join(__dirname, '..', '..', 'package.json'), // dist/server/../.. = repo root
+        path_1.default.join(__dirname, '..', 'package.json'), // fallback
+    ];
+    for (const pkgPath of pkgCandidates) {
+        try {
+            if (fs_1.default.existsSync(pkgPath)) {
+                const raw = JSON.parse(fs_1.default.readFileSync(pkgPath, 'utf8'));
+                if (raw.version) {
+                    version = raw.version;
+                    break;
+                }
+            }
+        }
+        catch { /* ignore */ }
+    }
+    const server = new ServerClass({ name: 'index', version }, { capabilities: { tools: { listChanged: true } } });
+    server.__declaredVersion = version;
+    // Never emit tools/list_changed before ready. Wrap sendToolListChanged to enforce ordering.
+    try {
+        const origSendToolListChanged = server.sendToolListChanged?.bind(server);
+        if (origSendToolListChanged && !server.__listPatched) {
+            server.__listPatched = true;
+            server.sendToolListChanged = (...a) => {
+                if (!server.__readyNotified) {
+                    server.__pendingListChanged = true;
+                    (0, handshakeManager_1.record)('buffer_list_changed_pre_ready');
+                    return;
+                }
+                return origSendToolListChanged(...a);
+            };
+        }
+    }
+    catch { /* ignore */ }
+    // Track ready notification + whether initialize was seen (ordering guarantee)
+    server.__readyNotified = false;
+    server.__sawInitializeRequest = false;
+    server.__initResponseSent = false;
+    // Single fallback watchdog if ready somehow suppressed.
+    if ((0, handshakeManager_1.isHandshakeFallbacksEnabled)()) {
+        setTimeout(() => {
+            try {
+                if (server.__sawInitializeRequest && !server.__readyNotified) {
+                    (0, handshakeManager_1.record)('watchdog_emit_ready');
+                    (0, handshakeManager_1.emitReadyGlobal)(server, 'watchdog');
+                }
+            }
+            catch { /* ignore */ }
+        }, 250).unref?.();
+    }
+    const requestSchema = (methodName) => zod_1.z.object({
+        jsonrpc: zod_1.z.literal('2.0'),
+        id: zod_1.z.union([zod_1.z.string(), zod_1.z.number()]).optional(),
+        method: zod_1.z.literal(methodName),
+        params: zod_1.z.any().optional()
+    });
+    // Explicit initialize handler – guarantees deterministic initialize response
+    // followed by exactly one server/ready notification.
+    server.setRequestHandler(requestSchema('initialize'), async (req) => {
+        try {
+            server.__sawInitializeRequest = true;
+            (0, handshakeManager_1.record)('initialize_received', { requestedProtocol: req?.params?.protocolVersion });
+            const requested = req?.params?.protocolVersion;
+            const negotiated = (0, handshakeManager_1.negotiateProtocolVersion)(requested);
+            const versionDeclared = server.__declaredVersion || server.version || '0.0.0';
+            const result = {
+                protocolVersion: negotiated,
+                serverInfo: { name: 'index', version: versionDeclared },
+                capabilities: { tools: { listChanged: true } },
+                instructions: 'Use initialize -> tools/list -> tools/call { name, arguments }. Health: tools/call health_check. Metrics: tools/call metrics_snapshot. Ping: ping.'
+            };
+            (0, handshakeManager_1.initFrameLog)('handler_return', { negotiated });
+            return result;
+        }
+        catch {
+            return { protocolVersion: handshakeManager_1.SUPPORTED_PROTOCOL_VERSIONS[0], serverInfo: { name: 'index', version: '0.0.0' }, capabilities: { tools: { listChanged: true } }, instructions: 'init fallback' };
+        }
+    });
+    // Legacy internal _oninitialize patch (will not trigger because we intercept initialize directly)
+    const originalInitInner = server._oninitialize?.bind(server);
+    if (originalInitInner && !server.__initPatched) {
+        server.__initPatched = true;
+        server._oninitialize = async function (request) {
+            const result = await originalInitInner(request);
+            try {
+                const negotiated = (0, handshakeManager_1.negotiateProtocolVersion)(request?.params?.protocolVersion);
+                result.protocolVersion = negotiated;
+                if (result && typeof result === 'object' && !('instructions' in result)) {
+                    result.instructions = 'Use initialize -> tools/list -> tools/call { name, arguments }. Health: tools/call health_check. Metrics: tools/call metrics_snapshot. Ping: ping.';
+                }
+                this.__sawInitializeRequest = true;
+            }
+            catch { /* ignore */ }
+            return result;
+        };
+    }
+    server.setRequestHandler(requestSchema('tools/list'), async () => {
+        (0, handshakeManager_1.record)('tools_list_request', { afterReady: !!server.__readyNotified, sawInit: !!server.__sawInitializeRequest });
+        const registry = (0, toolRegistry_1.getToolRegistry)();
+        return { tools: registry.map(r => ({ name: r.name, description: r.description, inputSchema: r.inputSchema })) };
+    });
+    // Raw handler for tools/call (MCP style) - returns content array
+    server.setRequestHandler(requestSchema('tools/call'), async (req) => {
+        const p = req?.params ?? {};
+        const name = p.name ?? '';
+        const args = p.arguments || {};
+        if (name === 'health_check')
+            (0, handshakeManager_1.record)('tools_call_health');
+        try {
+            if ((0, runtimeConfig_1.getRuntimeConfig)().logging.verbose)
+                process.stderr.write(`[rpc] call method=tools/call tool=${name} id=${req?.id ?? 'n/a'}\n`);
+        }
+        catch { /* ignore */ }
+        const handler = (0, registry_1.getHandler)(name);
+        if (!handler) {
+            throw { code: -32601, message: `Unknown tool: ${name}`, data: { message: `Unknown tool: ${name}`, method: name } };
+        }
+        try {
+            const result = await Promise.resolve(handler(args));
+            try {
+                if ((0, runtimeConfig_1.getRuntimeConfig)().logging.verbose)
+                    process.stderr.write(`[rpc] tool_result tool=${name} bytes=${Buffer.byteLength(JSON.stringify(result), 'utf8')}\n`);
+            }
+            catch { /* ignore */ }
+            return { content: [{ type: 'text', text: JSON.stringify(result, null, 2) }] };
+        }
+        catch (e) {
+            const code = e?.code;
+            const sem = e?.__semantic === true;
+            if (Number.isSafeInteger(code)) {
+                try {
+                    if ((0, runtimeConfig_1.getRuntimeConfig)().logging.verbose)
+                        process.stderr.write(`[rpc] tool_error_passthru tool=${name} code=${code} semantic=${sem ? '1' : '0'} msg=${e?.message || ''}\n`);
+                }
+                catch { /* ignore */ }
+                throw e;
+            }
+            const msg = e instanceof Error ? e.message : String(e);
+            try {
+                if ((0, runtimeConfig_1.getRuntimeConfig)().logging.verbose)
+                    process.stderr.write(`[rpc] tool_error_wrap tool=${name} msg=${msg.replace(/\s+/g, ' ')} code=${code ?? 'n/a'}\n`);
+            }
+            catch { /* ignore */ }
+            throw { code: -32603, message: 'Tool execution failed', data: { message: msg, method: name } };
+        }
+    });
+    // Lightweight ping handler (simple reachability / latency measurement)
+    server.setRequestHandler(requestSchema('ping'), async () => {
+        if (server.__sawInitializeRequest && server.__initResponseSent && !server.__readyNotified) {
+            (0, handshakeManager_1.emitReadyGlobal)(server, 'ping-trigger');
+        }
+        return { timestamp: new Date().toISOString(), uptimeMs: Math.round(process.uptime() * 1000) };
+    });
+    return server;
+}
+// Diagnostic accessor tool registered via dynamic side-effect (safe: tiny + read-only)
+try {
+    global.__MCP_HANDSHAKE_TRACE_TOOL__ = true;
+}
+catch { /* ignore */ }
+async function startSdkServer() {
+    // Lazy dynamic import once (first-call path)
+    if (!StdioServerTransport) {
+        let modServer, modStdio;
+        try {
+            modServer = await (0, transportFactory_1.dynamicImport)('@modelcontextprotocol/sdk/server/index.js');
+            modStdio = await (0, transportFactory_1.dynamicImport)('@modelcontextprotocol/sdk/server/stdio.js');
+        }
+        catch (e) {
+            try {
+                process.stderr.write(`[startup] sdk_dynamic_import_failed ${(e instanceof Error) ? e.message : String(e)}\n`);
+            }
+            catch { /* ignore */ }
+        }
+        try {
+            StdioServerTransport = modStdio?.StdioServerTransport;
+        }
+        catch { /* ignore */ }
+        let server;
+        try {
+            if (modServer?.Server)
+                server = createSdkServer(modServer.Server);
+        }
+        catch (e) {
+            try {
+                process.stderr.write(`[startup] sdk_server_create_failed ${(e instanceof Error) ? e.message : String(e)}\n`);
+            }
+            catch { /* ignore */ }
+        }
+        await (0, transportFactory_1.setupStdoutDiagnostics)();
+        (0, handshakeManager_1.setupStdinSniffer)(server);
+        if (!StdioServerTransport || !server) {
+            throw new Error('MCP SDK transport unavailable (removed fallback)');
+        }
+        (0, transportFactory_1.setupDispatcherOverride)(server);
+        const logDiag = (0, runtimeConfig_1.getRuntimeConfig)().logging.diagnostics;
+        if (logDiag) {
+            try {
+                process.stderr.write(`[transport-init] creating StdioServerTransport\n`);
+            }
+            catch { /* ignore */ }
+        }
+        const transport = new StdioServerTransport();
+        if (logDiag) {
+            try {
+                process.stderr.write(`[transport-init] connecting transport to server\n`);
+            }
+            catch { /* ignore */ }
+        }
+        await server.connect(transport);
+        if (logDiag) {
+            try {
+                const stdinReadable = process.stdin.readable;
+                const stdinListenerCount = process.stdin.listenerCount('data');
+                process.stderr.write(`[transport-init] transport connected stdin.readable=${stdinReadable} stdin.dataListeners=${stdinListenerCount}\n`);
+            }
+            catch { /* ignore */ }
+        }
+        (0, transportFactory_1.setupKeepalive)();
+        (0, handshakeManager_1.setupSafetyFallbacks)(server);
+        (0, transportFactory_1.wrapTransportSend)(server, transport);
+        return;
+    }
+    // Secondary path: StdioServerTransport already loaded
+    const modServer = await (0, transportFactory_1.dynamicImport)('@modelcontextprotocol/sdk/server/index.js');
+    const server = createSdkServer(modServer.Server);
+    const logDiag2 = (0, runtimeConfig_1.getRuntimeConfig)().logging.diagnostics;
+    if (logDiag2) {
+        try {
+            process.stderr.write(`[transport-init] (secondary) creating StdioServerTransport\n`);
+        }
+        catch { /* ignore */ }
+    }
+    const transport = new StdioServerTransport();
+    if (logDiag2) {
+        try {
+            process.stderr.write(`[transport-init] (secondary) connecting transport to server\n`);
+        }
+        catch { /* ignore */ }
+    }
+    await server.connect(transport);
+    if (logDiag2) {
+        try {
+            const stdinReadable = process.stdin.readable;
+            const stdinListenerCount = process.stdin.listenerCount('data');
+            process.stderr.write(`[transport-init] (secondary) transport connected stdin.readable=${stdinReadable} stdin.dataListeners=${stdinListenerCount}\n`);
+        }
+        catch { /* ignore */ }
+    }
+    (0, transportFactory_1.setupKeepalive)('secondary');
+    // Safety fallback timer (mirrors dynamic path) for missed ready emission
+    if ((0, handshakeManager_1.isHandshakeFallbacksEnabled)()) {
+        setTimeout(() => {
+            try {
+                if (server.__sawInitializeRequest && !server.__readyNotified) {
+                    (0, handshakeManager_1.handshakeLog)('safety_timeout_emit_attempt', { label: 'safety-timeout-100ms-secondary', sawInit: true, initRespSent: !!server.__initResponseSent });
+                    (0, handshakeManager_1.emitReadyGlobal)(server, 'safety-timeout-100ms-secondary');
+                }
+            }
+            catch { /* ignore */ }
+        }, 100).unref?.();
+    }
+}

package/dist/server/shutdownGuard.d.ts

@@ -0,0 +1,41 @@
+/**
+ * Shutdown Guard — Consolidates all process exit handling into a single
+ * re-entrance-guarded shutdown path.
+ *
+ * Fixes: GitHub Issue #36 — Multiple process.exit() race in shutdown paths
+ *
+ * Instead of SIGINT/SIGTERM/uncaughtException each independently calling
+ * process.exit(), all paths funnel through initiateShutdown() which:
+ * 1. Sets a guard flag to prevent re-entrance
+ * 2. Runs all registered cleanup handlers (with error isolation)
+ * 3. Returns the appropriate exit code
+ */
+export interface ShutdownGuard {
+    /**
+     * Register a named cleanup handler to run during shutdown.
+     * @param name - Unique identifier for this cleanup handler
+     * @param handler - Function to invoke during shutdown; errors are caught and logged
+     */
+    registerCleanup(name: string, handler: () => void): void;
+    /**
+     * Remove a previously registered cleanup handler.
+     * @param name - Identifier of the handler to remove
+     */
+    deregisterCleanup(name: string): void;
+    /**
+     * Initiate shutdown — only executes cleanup once (re-entrant calls return early).
+     * @param reason - Reason string; `'uncaughtException'` maps to exit code 1, all others to 0
+     * @returns The process exit code that callers should pass to `process.exit()`
+     */
+    initiateShutdown(reason: string): number;
+    /**
+     * Check if shutdown has been initiated.
+     * @returns `true` once {@link initiateShutdown} has been called
+     */
+    isShuttingDown(): boolean;
+}
+/**
+ * Create a new shutdown guard that consolidates all process exit paths into a single re-entrance-safe flow.
+ * @returns A {@link ShutdownGuard} instance with `registerCleanup`, `deregisterCleanup`, `initiateShutdown`, and `isShuttingDown` methods
+ */
+export declare function createShutdownGuard(): ShutdownGuard;

package/dist/server/shutdownGuard.js

@@ -0,0 +1,52 @@
+"use strict";
+/**
+ * Shutdown Guard — Consolidates all process exit handling into a single
+ * re-entrance-guarded shutdown path.
+ *
+ * Fixes: GitHub Issue #36 — Multiple process.exit() race in shutdown paths
+ *
+ * Instead of SIGINT/SIGTERM/uncaughtException each independently calling
+ * process.exit(), all paths funnel through initiateShutdown() which:
+ * 1. Sets a guard flag to prevent re-entrance
+ * 2. Runs all registered cleanup handlers (with error isolation)
+ * 3. Returns the appropriate exit code
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.createShutdownGuard = createShutdownGuard;
+/**
+ * Create a new shutdown guard that consolidates all process exit paths into a single re-entrance-safe flow.
+ * @returns A {@link ShutdownGuard} instance with `registerCleanup`, `deregisterCleanup`, `initiateShutdown`, and `isShuttingDown` methods
+ */
+function createShutdownGuard() {
+    let shuttingDown = false;
+    const cleanupHandlers = new Map();
+    return {
+        registerCleanup(name, handler) {
+            cleanupHandlers.set(name, handler);
+        },
+        deregisterCleanup(name) {
+            cleanupHandlers.delete(name);
+        },
+        initiateShutdown(reason) {
+            const exitCode = reason === 'uncaughtException' ? 1 : 0;
+            if (shuttingDown)
+                return exitCode;
+            shuttingDown = true;
+            for (const [name, handler] of cleanupHandlers) {
+                try {
+                    handler();
+                }
+                catch (err) {
+                    try {
+                        process.stderr.write(`[shutdown] cleanup handler "${name}" failed: ${err}\n`);
+                    }
+                    catch { /* ignore */ }
+                }
+            }
+            return exitCode;
+        },
+        isShuttingDown() {
+            return shuttingDown;
+        }
+    };
+}