@jagilber-org/index-server 1.22.0 → 1.26.1

package/dist/server/handshake/protocol.d.ts

@@ -0,0 +1,15 @@
+/** Supported protocol versions, ordered most-preferred-first. */
+export declare const SUPPORTED_PROTOCOL_VERSIONS: readonly string[];
+/**
+ * Negotiate a protocol version with graceful fallback.
+ * Returns the requested version when supported, otherwise the most preferred
+ * supported version.
+ */
+export declare function negotiateProtocolVersion(requested?: string): string;
+/**
+ * By default ALL non-primary ready fallbacks (watchdogs, safety timeouts,
+ * stdin sniff synthetic initialize, unconditional init fallbacks, etc.) are
+ * disabled. Enable via INDEX_SERVER_INIT_FEATURES=handshakeFallbacks to
+ * re-enable the safety nets.
+ */
+export declare function isHandshakeFallbacksEnabled(): boolean;

package/dist/server/handshake/protocol.js

@@ -0,0 +1,37 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.SUPPORTED_PROTOCOL_VERSIONS = void 0;
+exports.negotiateProtocolVersion = negotiateProtocolVersion;
+exports.isHandshakeFallbacksEnabled = isHandshakeFallbacksEnabled;
+/**
+ * Pure protocol-version negotiation utilities for the MCP handshake.
+ * No I/O, no module-level mutable state.
+ */
+const runtimeConfig_1 = require("../../config/runtimeConfig");
+/** Supported protocol versions, ordered most-preferred-first. */
+exports.SUPPORTED_PROTOCOL_VERSIONS = [
+    '2025-06-18',
+    '2024-11-05',
+    '2024-10-07',
+];
+/**
+ * Negotiate a protocol version with graceful fallback.
+ * Returns the requested version when supported, otherwise the most preferred
+ * supported version.
+ */
+function negotiateProtocolVersion(requested) {
+    if (!requested)
+        return exports.SUPPORTED_PROTOCOL_VERSIONS[0];
+    if (exports.SUPPORTED_PROTOCOL_VERSIONS.includes(requested))
+        return requested;
+    return exports.SUPPORTED_PROTOCOL_VERSIONS[0];
+}
+/**
+ * By default ALL non-primary ready fallbacks (watchdogs, safety timeouts,
+ * stdin sniff synthetic initialize, unconditional init fallbacks, etc.) are
+ * disabled. Enable via INDEX_SERVER_INIT_FEATURES=handshakeFallbacks to
+ * re-enable the safety nets.
+ */
+function isHandshakeFallbacksEnabled() {
+    return (0, runtimeConfig_1.getRuntimeConfig)().initFeatures.has('handshakeFallbacks');
+}

package/dist/server/handshake/readyEmitter.d.ts

@@ -0,0 +1,6 @@
+/**
+ * Idempotent emission of `server/ready`. Invoked ONLY after the initialize
+ * response has been (or is about to be) flushed unless the caller is one of
+ * the explicit fallback paths AND fallback safety nets are enabled.
+ */
+export declare function emitReadyGlobal(server: any, reason: string): void;

package/dist/server/handshake/readyEmitter.js

@@ -0,0 +1,88 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.emitReadyGlobal = emitReadyGlobal;
+/* eslint-disable @typescript-eslint/no-explicit-any */
+/**
+ * `server/ready` notification dispatcher. Owns the unique ordering and
+ * fallback logic for emitting the ready signal exactly once.
+ */
+const mcpLogBridge_1 = require("../../services/mcpLogBridge");
+const protocol_1 = require("./protocol");
+const tracing_1 = require("./tracing");
+const FALLBACK_REASONS_ALLOWED_BEFORE_INIT_RESPONSE = new Set([
+    'unconditional-init-fallback',
+    'unconditional-init-fallback-direct',
+    'forced-init-fallback',
+]);
+/**
+ * Idempotent emission of `server/ready`. Invoked ONLY after the initialize
+ * response has been (or is about to be) flushed unless the caller is one of
+ * the explicit fallback paths AND fallback safety nets are enabled.
+ */
+function emitReadyGlobal(server, reason) {
+    try {
+        if (!server)
+            return;
+        if (server.__readyNotified)
+            return;
+        if (!server.__initResponseSent) {
+            if (!(0, protocol_1.isHandshakeFallbacksEnabled)())
+                return; // strict mode: never emit early
+            if (!FALLBACK_REASONS_ALLOWED_BEFORE_INIT_RESPONSE.has(reason))
+                return;
+        }
+        const v = server.__declaredVersion || server.version || '0.0.0';
+        server.__readyNotified = true;
+        (0, mcpLogBridge_1.activateMcpLogBridge)();
+        (0, tracing_1.record)('ready_emitted', { reason, version: v });
+        try {
+            process.stderr.write(`[ready] emit reason=${reason} version=${v}\n`);
+        }
+        catch (err) {
+            (0, tracing_1.handshakeError)('emitReadyGlobal:log', err);
+        }
+        const msg = { jsonrpc: '2.0', method: 'server/ready', params: { version: v } };
+        let dispatched = false;
+        try {
+            const t = server._transport;
+            if (t?.send) {
+                t.send(msg)?.catch?.((err) => {
+                    (0, tracing_1.handshakeError)('transport.send(ready)', err);
+                });
+                dispatched = true;
+            }
+        }
+        catch (err) {
+            (0, tracing_1.handshakeError)('emitReadyGlobal:transport', err);
+        }
+        if (!dispatched) {
+            try {
+                server.sendNotification?.({ method: 'server/ready', params: { version: v } });
+                dispatched = true;
+            }
+            catch (err) {
+                (0, tracing_1.handshakeError)('emitReadyGlobal:sendNotification', err);
+            }
+        }
+        if (!dispatched) {
+            try {
+                process.stdout.write(JSON.stringify(msg) + '\n');
+            }
+            catch (err) {
+                (0, tracing_1.handshakeError)('emitReadyGlobal:stdout', err);
+            }
+        }
+        try {
+            if (typeof server.sendToolListChanged === 'function') {
+                server.sendToolListChanged();
+                (0, tracing_1.record)('list_changed_after_ready');
+            }
+        }
+        catch (err) {
+            (0, tracing_1.handshakeError)('emitReadyGlobal:sendToolListChanged', err);
+        }
+    }
+    catch (err) {
+        (0, tracing_1.handshakeError)('emitReadyGlobal:outer', err);
+    }
+}

package/dist/server/handshake/safetyFallbacks.d.ts

@@ -0,0 +1 @@
+export declare function setupSafetyFallbacks(server: any): void;

package/dist/server/handshake/safetyFallbacks.js

@@ -0,0 +1,134 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.setupSafetyFallbacks = setupSafetyFallbacks;
+/* eslint-disable @typescript-eslint/no-explicit-any */
+/**
+ * Safety fallback timers and `_oninitialize` SDK patch. Provides last-resort
+ * ready emission and unconditional initialize-response fabrication when no
+ * other path has produced one within tight deadlines.
+ */
+const runtimeConfig_1 = require("../../config/runtimeConfig");
+const fallbackFrames_1 = require("./fallbackFrames");
+const protocol_1 = require("./protocol");
+const readyEmitter_1 = require("./readyEmitter");
+const tracing_1 = require("./tracing");
+const SAFETY_TIMEOUT_MS = 100;
+const UNCONDITIONAL_FALLBACK_MS = 150;
+const FALLBACK_NEGOTIATED_VERSION = '2024-11-05';
+function setupSafetyFallbacks(server) {
+    if ((0, protocol_1.isHandshakeFallbacksEnabled)()) {
+        setTimeout(() => {
+            try {
+                if (server.__sawInitializeRequest &&
+                    server.__initResponseSent &&
+                    !server.__readyNotified) {
+                    (0, tracing_1.handshakeLog)('safety_timeout_emit_attempt', {
+                        label: 'safety-timeout-100ms',
+                        sawInit: true,
+                        initRespSent: true,
+                    });
+                    (0, readyEmitter_1.emitReadyGlobal)(server, 'safety-timeout-100ms');
+                }
+            }
+            catch (err) {
+                (0, tracing_1.handshakeError)('safetyFallback:100ms', err);
+            }
+        }, SAFETY_TIMEOUT_MS).unref?.();
+    }
+    if ((0, protocol_1.isHandshakeFallbacksEnabled)()) {
+        setTimeout(() => {
+            try {
+                const cfg = (0, runtimeConfig_1.getRuntimeConfig)();
+                const INIT_FALLBACK_ENABLED = cfg.initFeatures.has('initFallback');
+                if (cfg.trace.has('healthMixed') && !server.__initResponseSent) {
+                    if (!INIT_FALLBACK_ENABLED) {
+                        try {
+                            process.stderr.write(`[diag] ${Date.now()} init_unconditional_fallback_skip gating_off\n`);
+                        }
+                        catch (err) {
+                            (0, tracing_1.handshakeError)('safetyFallback:skipLog', err);
+                        }
+                        return;
+                    }
+                    if (!server.__sawInitializeRequest) {
+                        if (process.stderr && !server.__diagForcedInitLogged) {
+                            server.__diagForcedInitLogged = true;
+                            try {
+                                process.stderr.write(`[diag] ${Date.now()} init_unconditional_fallback_emit id=1 reason=no_init_seen_150ms\n`);
+                            }
+                            catch (err) {
+                                (0, tracing_1.handshakeError)('safetyFallback:noInitLog', err);
+                            }
+                        }
+                    }
+                    else {
+                        try {
+                            process.stderr.write(`[diag] ${Date.now()} init_unconditional_fallback_emit id=1 reason=init_seen_no_response_150ms\n`);
+                        }
+                        catch (err) {
+                            (0, tracing_1.handshakeError)('safetyFallback:initSeenLog', err);
+                        }
+                    }
+                    const frame = (0, fallbackFrames_1.buildForcedInitResultFrame)(FALLBACK_NEGOTIATED_VERSION, 'unconditional-init-fallback', 1);
+                    const tr = server._transport || server.__transportRef;
+                    server.__initResponseSent = true;
+                    if (tr && typeof tr.send === 'function') {
+                        Promise.resolve(tr.send(frame))
+                            .then(() => {
+                            if (!server.__readyNotified)
+                                (0, readyEmitter_1.emitReadyGlobal)(server, 'unconditional-init-fallback');
+                        })
+                            .catch((err) => {
+                            (0, tracing_1.handshakeError)('unconditionalFallback:transport.send', err);
+                        });
+                    }
+                    else {
+                        try {
+                            process.stdout.write(JSON.stringify(frame) + '\n');
+                        }
+                        catch (err) {
+                            (0, tracing_1.handshakeError)('unconditionalFallback:stdout', err);
+                        }
+                        if (!server.__readyNotified)
+                            (0, readyEmitter_1.emitReadyGlobal)(server, 'unconditional-init-fallback-direct');
+                    }
+                }
+            }
+            catch (err) {
+                (0, tracing_1.handshakeError)('safetyFallback:150ms', err);
+            }
+        }, UNCONDITIONAL_FALLBACK_MS).unref?.();
+    }
+    // Patch initialize result for instructions (SDK internal property)
+    const originalInit = server._oninitialize;
+    if (originalInit && !server.__initPatched) {
+        server.__initPatched = true;
+        server._oninitialize = async function (request) {
+            try {
+                this.__sawInitializeRequest = true;
+                (0, tracing_1.handshakeLog)('oninitialize_enter', {
+                    sawInit: true,
+                    ready: !!this.__readyNotified,
+                    initRespSent: !!server.__initResponseSent,
+                });
+            }
+            catch (err) {
+                (0, tracing_1.handshakeError)('oninitialize:enter', err);
+            }
+            const result = await originalInit.call(this, request);
+            try {
+                const negotiated = (0, protocol_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.';
+                }
+                // Do NOT emit server/ready here; ordering handled strictly by transport send hook.
+            }
+            catch (err) {
+                (0, tracing_1.handshakeError)('oninitialize:negotiation', err);
+            }
+            return result;
+        };
+    }
+}

package/dist/server/handshake/stdinSniffer.d.ts

@@ -0,0 +1 @@
+export declare function setupStdinSniffer(server: any): void;

package/dist/server/handshake/stdinSniffer.js

@@ -0,0 +1,260 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.setupStdinSniffer = setupStdinSniffer;
+/* eslint-disable @typescript-eslint/no-explicit-any */
+/**
+ * Pre-connect stdin sniffer: scans incoming bytes for an MCP `initialize`
+ * request even when fragmented across chunks, then drives a layered
+ * fallback chain (synthetic dispatch -> forced result -> ready emission)
+ * when the SDK request dispatcher fails to make progress on its own.
+ */
+const runtimeConfig_1 = require("../../config/runtimeConfig");
+const initializeDetector_1 = require("./initializeDetector");
+const fallbackFrames_1 = require("./fallbackFrames");
+const protocol_1 = require("./protocol");
+const readyEmitter_1 = require("./readyEmitter");
+const tracing_1 = require("./tracing");
+const SNIFF_WINDOW_BYTES = 8000;
+const BUFFER_HARD_LIMIT = 10_000;
+const BUFFER_TRIM_TAIL = 2048;
+const SCHEDULE_DETECT_MS = 60;
+const SCHEDULE_SYNTHETIC_MS = 40;
+const SCHEDULE_FORCED_RESULT_MS = 140;
+function setupStdinSniffer(server) {
+    try {
+        const cfg = (0, runtimeConfig_1.getRuntimeConfig)();
+        const disableInitSniff = cfg.initFeatures.has('disableSniff');
+        if (!server || disableInitSniff)
+            return;
+        const INIT_FALLBACK_ENABLED = cfg.initFeatures.has('initFallback');
+        let __sniffBuf = '';
+        if (cfg.trace.has('healthMixed')) {
+            try {
+                if (!server.__diagRQMap) {
+                    server.__diagRQMap = new Map();
+                    server.__diagQueueDepthSniff = 0;
+                }
+            }
+            catch (err) {
+                (0, tracing_1.handshakeError)('setupStdinSniffer:diagMapInit', err);
+            }
+        }
+        process.stdin.on('data', (chunk) => {
+            try {
+                const healthMixed = cfg.trace.has('healthMixed');
+                if (healthMixed && !server.__diagFirstChunkLogged) {
+                    server.__diagFirstChunkLogged = true;
+                    const raw = chunk.toString('utf8');
+                    const snippet = raw.replace(/\r/g, ' ').replace(/\n/g, '\\n').slice(0, 240);
+                    process.stderr.write(`[diag] ${Date.now()} stdin_first_chunk size=${chunk.length} snippet="${snippet}"\n`);
+                }
+                __sniffBuf += chunk.toString('utf8');
+                if (!server.__sniffedInit) {
+                    const bufForScan = __sniffBuf.slice(-SNIFF_WINDOW_BYTES);
+                    const detect = (0, initializeDetector_1.detectInitializeMethod)(bufForScan, healthMixed);
+                    if (detect.mode) {
+                        handleInitializeDetected({
+                            server,
+                            bufForScan,
+                            mode: detect.mode,
+                            healthMixed,
+                            initFallbackEnabled: INIT_FALLBACK_ENABLED,
+                        });
+                    }
+                }
+                if (healthMixed && !server.__dispatcherOverrideActive) {
+                    __sniffBuf = drainDiagFrames(__sniffBuf, server);
+                }
+                if (__sniffBuf.length > BUFFER_HARD_LIMIT) {
+                    __sniffBuf = __sniffBuf.slice(-BUFFER_TRIM_TAIL);
+                }
+            }
+            catch (err) {
+                (0, tracing_1.handshakeError)('stdinSniff:data', err);
+            }
+        });
+    }
+    catch (err) {
+        (0, tracing_1.handshakeError)('setupStdinSniffer', err);
+    }
+}
+function handleInitializeDetected(args) {
+    const { server, bufForScan, mode, healthMixed, initFallbackEnabled } = args;
+    server.__sniffedInit = true;
+    if (healthMixed) {
+        try {
+            const norm = bufForScan.slice(0, 400).replace(/\r/g, ' ').replace(/\n/g, '\\n');
+            process.stderr.write(`[diag] ${Date.now()} sniff_init_${mode}_detect buffer_bytes=${bufForScan.length} preview="${norm}"\n`);
+        }
+        catch (err) {
+            (0, tracing_1.handshakeError)('stdinSniff:diagPreview', err);
+        }
+    }
+    setTimeout(() => {
+        try {
+            if (!server.__sawInitializeRequest) {
+                server.__sawInitializeRequest = true;
+                if (healthMixed) {
+                    try {
+                        process.stderr.write(`[diag] ${Date.now()} sniff_init_mark_sawInit mode=${mode}\n`);
+                    }
+                    catch (err) {
+                        (0, tracing_1.handshakeError)('stdinSniff:sawInitLog', err);
+                    }
+                }
+            }
+            if (initFallbackEnabled && !server.__initResponseSent) {
+                scheduleSyntheticInitDispatch(server, bufForScan, healthMixed);
+                scheduleForcedInitResult(server, healthMixed);
+            }
+            else if (healthMixed) {
+                try {
+                    process.stderr.write(`[diag] ${Date.now()} sniff_init_forced_result_skip gating_off\n`);
+                }
+                catch (err) {
+                    (0, tracing_1.handshakeError)('stdinSniff:forcedResultSkipLog', err);
+                }
+            }
+            if ((0, protocol_1.isHandshakeFallbacksEnabled)()) {
+                if (server.__initResponseSent && !server.__readyNotified) {
+                    (0, readyEmitter_1.emitReadyGlobal)(server, 'stdin-sniff-fallback');
+                }
+            }
+        }
+        catch (err) {
+            (0, tracing_1.handshakeError)('stdinSniff:initSchedule', err);
+        }
+    }, SCHEDULE_DETECT_MS).unref?.();
+}
+function scheduleSyntheticInitDispatch(server, bufForScan, healthMixed) {
+    setTimeout(() => {
+        try {
+            if (server.__initResponseSent || server.__syntheticInitDispatched)
+                return;
+            const id = (0, initializeDetector_1.extractRequestId)(bufForScan) ?? 1;
+            const req = (0, fallbackFrames_1.buildSyntheticInitRequest)(id);
+            server.__syntheticInitDispatched = true;
+            const dispatch = server._onRequest || server._onrequest;
+            if (typeof dispatch === 'function') {
+                if (healthMixed) {
+                    try {
+                        process.stderr.write(`[diag] ${Date.now()} sniff_init_synthetic_dispatch id=${id}\n`);
+                    }
+                    catch (err) {
+                        (0, tracing_1.handshakeError)('stdinSniff:syntheticDispatchLog', err);
+                    }
+                }
+                try {
+                    dispatch.call(server, req);
+                }
+                catch (err) {
+                    (0, tracing_1.handshakeError)('syntheticInitDispatch', err);
+                }
+            }
+        }
+        catch (err) {
+            (0, tracing_1.handshakeError)('syntheticInitOuter', err);
+        }
+    }, SCHEDULE_SYNTHETIC_MS).unref?.();
+}
+function scheduleForcedInitResult(server, healthMixed) {
+    setTimeout(() => {
+        try {
+            if (server.__initResponseSent)
+                return;
+            const tr = server._transport || server.__transportRef;
+            if (tr && typeof tr.send === 'function') {
+                let negotiated = '2024-11-05';
+                try {
+                    negotiated = (0, protocol_1.negotiateProtocolVersion)('2024-11-05') || negotiated;
+                }
+                catch (err) {
+                    (0, tracing_1.handshakeError)('stdinSniff:negotiateVersion', err);
+                }
+                const frame = (0, fallbackFrames_1.buildForcedInitResultFrame)(negotiated, 'forced-init-fallback', 1);
+                server.__initResponseSent = true;
+                if (healthMixed) {
+                    try {
+                        process.stderr.write(`[diag] ${Date.now()} sniff_init_forced_result_emit id=1 negotiated=${negotiated}\n`);
+                    }
+                    catch (err) {
+                        (0, tracing_1.handshakeError)('stdinSniff:forcedResultLog', err);
+                    }
+                }
+                Promise.resolve(tr.send(frame))
+                    .then(() => {
+                    if (!server.__readyNotified)
+                        (0, readyEmitter_1.emitReadyGlobal)(server, 'forced-init-fallback');
+                })
+                    .catch((err) => {
+                    (0, tracing_1.handshakeError)('forcedInitFallback:transport.send', err);
+                });
+            }
+        }
+        catch (err) {
+            (0, tracing_1.handshakeError)('forcedInitFallback:outer', err);
+        }
+    }, SCHEDULE_FORCED_RESULT_MS).unref?.();
+}
+function drainDiagFrames(buf, server) {
+    try {
+        let working = buf;
+        let idx;
+        while ((idx = working.indexOf('\n')) !== -1) {
+            const line = working.slice(0, idx).trim();
+            working = working.slice(idx + 1);
+            if (!line)
+                continue;
+            let obj;
+            try {
+                obj = JSON.parse(line);
+            }
+            catch (e) {
+                if (/jsonrpc|method/i.test(line)) {
+                    const frag = line.replace(/\r/g, ' ').replace(/\n/g, ' ').slice(0, 200);
+                    process.stderr.write(`[diag] ${Date.now()} malformed_json_line len=${line.length} frag="${frag}" err=${e.message || e}\n`);
+                }
+                continue;
+            }
+            if (obj &&
+                obj.jsonrpc === '2.0' &&
+                obj.method &&
+                Object.prototype.hasOwnProperty.call(obj, 'id')) {
+                const metaName = obj.method === 'tools/call' ? obj?.params?.name : '';
+                const category = (() => {
+                    if (obj.method === 'initialize')
+                        return 'init';
+                    if (obj.method === 'health_check' || metaName === 'health_check')
+                        return 'health';
+                    if (obj.method === 'metrics_snapshot' || metaName === 'metrics_snapshot')
+                        return 'metrics';
+                    if (metaName === 'meta_tools')
+                        return 'meta';
+                    return 'other';
+                })();
+                if (category === 'health' ||
+                    category === 'metrics' ||
+                    category === 'meta' ||
+                    category === 'init') {
+                    try {
+                        server.__diagQueueDepthSniff++;
+                        server.__diagRQMap.set(obj.id, {
+                            start: Date.now(),
+                            cat: category,
+                            method: obj.method,
+                        });
+                        process.stderr.write(`[diag] ${Date.now()} rq_enqueue method=${obj.method} cat=${category} id=${obj.id} qdepth=${server.__diagQueueDepthSniff} src=sniff\n`);
+                    }
+                    catch (err) {
+                        (0, tracing_1.handshakeError)('stdinSniff:diagEnqueue', err);
+                    }
+                }
+            }
+        }
+        return working;
+    }
+    catch (err) {
+        (0, tracing_1.handshakeError)('stdinSniff:diagEnqueue', err);
+        return buf;
+    }
+}

package/dist/server/handshake/tracing.d.ts

@@ -0,0 +1,16 @@
+export declare function isHandshakeTraceEnabled(): boolean;
+export interface HandshakeEvent {
+    seq: number;
+    ts: string;
+    stage: string;
+    extra?: Record<string, unknown>;
+}
+export declare function getHandshakeEvents(): readonly HandshakeEvent[];
+/** Write a single handshake-error breadcrumb to stderr without throwing. */
+export declare function handshakeError(context: string, err: unknown): void;
+export declare function handshakeLog(stage: string, data?: Record<string, unknown>): void;
+export declare function record(stage: string, extra?: Record<string, unknown>): void;
+export declare function isInitFrameDiagEnabled(): boolean;
+export declare function initFrameLog(stage: string, extra?: Record<string, unknown>): void;
+/** Expose the events ring on globalThis for the diagnostics_handshake tool. */
+export declare function exposeGlobalEventsRef(): void;

package/dist/server/handshake/tracing.js

@@ -0,0 +1,95 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.isHandshakeTraceEnabled = isHandshakeTraceEnabled;
+exports.getHandshakeEvents = getHandshakeEvents;
+exports.handshakeError = handshakeError;
+exports.handshakeLog = handshakeLog;
+exports.record = record;
+exports.isInitFrameDiagEnabled = isInitFrameDiagEnabled;
+exports.initFrameLog = initFrameLog;
+exports.exposeGlobalEventsRef = exposeGlobalEventsRef;
+/**
+ * Handshake tracing primitives — module-scoped sequence counter, ring buffer,
+ * stderr-safe loggers, and the `handshakeError` helper used everywhere a
+ * handshake-adjacent catch block would otherwise silently swallow an error.
+ */
+const runtimeConfig_1 = require("../../config/runtimeConfig");
+function isHandshakeTraceEnabled() {
+    return (0, runtimeConfig_1.getRuntimeConfig)().trace.has('handshake');
+}
+let HANDSHAKE_SEQ = 0;
+const HANDSHAKE_EVENTS = [];
+function getHandshakeEvents() {
+    return HANDSHAKE_EVENTS;
+}
+/** Write a single handshake-error breadcrumb to stderr without throwing. */
+function handshakeError(context, err) {
+    try {
+        process.stderr.write(`[handshake-error] ${context}: ${err.message || String(err)}\n`);
+    }
+    catch {
+        /* stderr write failed — truly nothing we can do */
+    }
+}
+function handshakeLog(stage, data) {
+    if (!isHandshakeTraceEnabled())
+        return;
+    try {
+        const payload = {
+            handshake: true,
+            seq: ++HANDSHAKE_SEQ,
+            ts: new Date().toISOString(),
+            stage,
+            ...(data || {}),
+        };
+        process.stderr.write(`[handshake] ${JSON.stringify(payload)}\n`);
+    }
+    catch (err) {
+        handshakeError('handshakeLog', err);
+    }
+}
+function record(stage, extra) {
+    const evt = {
+        seq: ++HANDSHAKE_SEQ,
+        ts: new Date().toISOString(),
+        stage,
+        extra,
+    };
+    HANDSHAKE_EVENTS.push(evt);
+    if (HANDSHAKE_EVENTS.length > 50)
+        HANDSHAKE_EVENTS.shift();
+    if (isHandshakeTraceEnabled()) {
+        try {
+            process.stderr.write(`[handshake] ${JSON.stringify(evt)}\n`);
+        }
+        catch (err) {
+            handshakeError('record:trace', err);
+        }
+    }
+}
+function isInitFrameDiagEnabled() {
+    return (0, runtimeConfig_1.getRuntimeConfig)().trace.has('initFrame');
+}
+function initFrameLog(stage, extra) {
+    if (!isInitFrameDiagEnabled())
+        return;
+    try {
+        const payload = { stage, t: Date.now(), ...(extra || {}) };
+        process.stderr.write(`[init-frame] ${JSON.stringify(payload)}\n`);
+    }
+    catch (err) {
+        handshakeError('initFrameLog', err);
+    }
+}
+/** Expose the events ring on globalThis for the diagnostics_handshake tool. */
+function exposeGlobalEventsRef() {
+    try {
+        global.HANDSHAKE_EVENTS_REF =
+            HANDSHAKE_EVENTS;
+    }
+    catch (err) {
+        handshakeError('globalEventsRef', err);
+    }
+}
+// Eager side effect preserved from legacy handshakeManager.ts module-load behavior.
+exposeGlobalEventsRef();