@jagilber-org/index-server 1.19.1

package/dist/server/transportFactory.js

@@ -0,0 +1,429 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.dynamicImport = void 0;
+exports.setupStdoutDiagnostics = setupStdoutDiagnostics;
+exports.setupDispatcherOverride = setupDispatcherOverride;
+exports.wrapTransportSend = wrapTransportSend;
+exports.setupKeepalive = setupKeepalive;
+/* eslint-disable @typescript-eslint/no-explicit-any */
+/**
+ * Transport initialization, request dispatcher override, and diagnostics
+ * wrappers for the MCP server.
+ */
+const runtimeConfig_1 = require("../config/runtimeConfig");
+const handshakeManager_1 = require("./handshakeManager");
+// Helper to perform a true dynamic ESM import that TypeScript won't down-level to require()
+const dynamicImport = (specifier) => (Function('m', 'return import(m);'))(specifier);
+exports.dynamicImport = dynamicImport;
+/**
+ * Set up stdout diagnostics wrapper for backpressure monitoring.
+ * Enabled via INDEX_SERVER_TRACE=healthMixed.
+ */
+async function setupStdoutDiagnostics() {
+    const __diagEnabled = (0, runtimeConfig_1.getRuntimeConfig)().trace.has('healthMixed');
+    const __diag = (msg) => { if (__diagEnabled) {
+        try {
+            process.stderr.write(`[diag] ${Date.now()} ${msg}\n`);
+        }
+        catch { /* ignore */ }
+    } };
+    // Emit a one-time version marker so tests can assert the newer diagnostic wrapper code is actually loaded.
+    if (__diagEnabled) {
+        try {
+            const buildMarker = 'sdkServerDiagV1';
+            // Include a coarse content hash surrogate: file size + mtime if available
+            let fsMeta = '';
+            try {
+                const fsMod = await import('fs');
+                const stat = fsMod.statSync(__filename);
+                fsMeta = ` size=${stat.size} mtimeMs=${Math.trunc(stat.mtimeMs)}`;
+            }
+            catch { /* ignore meta */ }
+            process.stderr.write(`[diag] ${Date.now()} diag_start marker=${buildMarker}${fsMeta}\n`);
+        }
+        catch { /* ignore */ }
+    }
+    if (__diagEnabled) {
+        try {
+            const origWrite = process.stdout.write.bind(process.stdout);
+            let backpressureEvents = 0;
+            let bytesTotal = 0;
+            let lastReportAt = Date.now();
+            process.stdout.on?.('drain', () => { __diag('stdout_drain'); });
+            process.stdout.write = function (chunk, encoding, cb) {
+                try {
+                    const size = Buffer.isBuffer(chunk) ? chunk.length : Buffer.byteLength(String(chunk));
+                    bytesTotal += size;
+                    const ret = origWrite(chunk, encoding, cb);
+                    if (!ret) {
+                        backpressureEvents++;
+                        __diag(`stdout_backpressure size=${size} backpressureEvents=${backpressureEvents}`);
+                    }
+                    const now = Date.now();
+                    if (now - lastReportAt > 2000) {
+                        __diag(`stdout_summary bytesTotal=${bytesTotal} backpressureEvents=${backpressureEvents}`);
+                        lastReportAt = now;
+                    }
+                    return ret;
+                }
+                catch (e) {
+                    try {
+                        __diag(`stdout_write_wrapper_error ${e?.message || String(e)}`);
+                    }
+                    catch { /* ignore */ }
+                    return origWrite(chunk, encoding, cb);
+                }
+            };
+        }
+        catch { /* ignore */ }
+    }
+}
+// Robust semantic error preservation: deep scan for JSON-RPC code/message
+function deepScan(obj, depth = 0, seen = new Set()) {
+    if (!obj || typeof obj !== 'object' || depth > 4 || seen.has(obj))
+        return undefined;
+    seen.add(obj);
+    if (Number.isSafeInteger(obj.code)) {
+        const c = obj.code;
+        if (c === -32601 || c === -32602)
+            return c; // prioritize semantic validation codes
+    }
+    // Prefer specific well-known nesting keys first
+    const keys = ['error', 'original', 'cause', 'data'];
+    for (const k of keys) {
+        try {
+            const child = obj[k];
+            const found = deepScan(child, depth + 1, seen);
+            if (found !== undefined)
+                return found;
+        }
+        catch { /* ignore */ }
+    }
+    // Fallback: generic property iteration (shallow) to catch unexpected wrappers
+    if (depth < 2) {
+        try {
+            for (const v of Object.values(obj)) {
+                const found = deepScan(v, depth + 1, seen);
+                if (found !== undefined)
+                    return found;
+            }
+        }
+        catch { /* ignore */ }
+    }
+    return undefined;
+}
+// Categorize request for diagnostics
+function categorizeRequest(request) {
+    const metaName = request.method === 'tools/call' ? request?.params?.name : '';
+    if (request.method === 'initialize')
+        return 'init';
+    if (request.method === 'health_check' || metaName === 'health_check')
+        return 'health';
+    if (request.method === 'metrics_snapshot' || metaName === 'metrics_snapshot')
+        return 'metrics';
+    if (metaName === 'meta_tools')
+        return 'meta';
+    return 'other';
+}
+/**
+ * Override the internal request dispatcher to retain error.data & emit diagnostics.
+ * The upstream SDK has used both `_onRequest` (camel) and `_onrequest` (lower) across versions;
+ * we defensively hook whichever exists and assign our wrapper to BOTH names.
+ */
+function setupDispatcherOverride(server) {
+    const existingLower = server._onrequest;
+    const existingCamel = server._onRequest;
+    const originalOnRequest = (existingCamel || existingLower) ? (existingCamel || existingLower).bind(server) : undefined;
+    let __diagQueueDepth = 0;
+    if (originalOnRequest) {
+        const wrapped = function (request) {
+            const diagEnabled = (0, runtimeConfig_1.getRuntimeConfig)().trace.has('healthMixed');
+            let startedAt;
+            if (diagEnabled) {
+                const category = categorizeRequest(request);
+                if (category === 'health' || category === 'meta' || category === 'metrics' || category === 'init') {
+                    startedAt = Date.now();
+                    try {
+                        __diagQueueDepth++;
+                        process.stderr.write(`[diag] ${startedAt} rq_enqueue method=${request.method} cat=${category} id=${request.id} qdepth=${__diagQueueDepth}\n`);
+                        if (category === 'health') {
+                            if (!server.__firstHealthEnqueueAt) {
+                                server.__firstHealthEnqueueAt = startedAt;
+                            }
+                            if (request.id === 1 && !server.__healthId1EnqueueAt) {
+                                server.__healthId1EnqueueAt = startedAt;
+                            }
+                        }
+                        if (!server.__activeDiagRequests) {
+                            server.__activeDiagRequests = new Map();
+                        }
+                        server.__activeDiagRequests.set(request.id, { id: request.id, method: request.method, cat: category, start: startedAt });
+                        // Mis-order detection: health/metrics/meta before initialize observed
+                        if ((category === 'health' || category === 'metrics' || category === 'meta') && !server.__sawInitializeRequest) {
+                            try {
+                                process.stderr.write(`[diag] ${Date.now()} rq_misorder_before_init method=${request.method} id=${request.id} cat=${category} qdepth=${__diagQueueDepth}\n`);
+                            }
+                            catch { /* ignore */ }
+                        }
+                    }
+                    catch { /* ignore */ }
+                }
+            }
+            const handler = this._requestHandlers.get(request.method) ?? this.fallbackRequestHandler;
+            if (handler === undefined) {
+                return this._transport?.send({ jsonrpc: '2.0', id: request.id, error: { code: -32601, message: 'Method not found', data: { method: request.method } } }).catch(() => { });
+            }
+            const abortController = new AbortController();
+            this._requestHandlerAbortControllers.set(request.id, abortController);
+            // IMPORTANT: We intentionally never early-return without sending a response
+            Promise.resolve()
+                .then(() => handler(request, { signal: abortController.signal }))
+                .then((result) => {
+                if (startedAt !== undefined) {
+                    try {
+                        const dur = Date.now() - startedAt;
+                        const category = categorizeRequest(request);
+                        if (category === 'health' || category === 'meta' || category === 'metrics' || category === 'init') {
+                            __diagQueueDepth = Math.max(0, __diagQueueDepth - 1);
+                            process.stderr.write(`[diag] ${Date.now()} rq_complete method=${request.method} cat=${category} id=${request.id} dur_ms=${dur} qdepth=${__diagQueueDepth}\n`);
+                            try {
+                                server.__activeDiagRequests?.delete(request.id);
+                            }
+                            catch { /* ignore */ }
+                        }
+                    }
+                    catch { /* ignore */ }
+                }
+                if (abortController.signal.aborted) {
+                    try {
+                        if ((0, runtimeConfig_1.getRuntimeConfig)().logging.verbose)
+                            process.stderr.write(`[rpc] aborted-but-sending method=${request.method} id=${request.id}\n`);
+                    }
+                    catch { /* ignore */ }
+                }
+                else {
+                    try {
+                        if ((0, runtimeConfig_1.getRuntimeConfig)().logging.verbose)
+                            process.stderr.write(`[rpc] response method=${request.method} id=${request.id} ok\n`);
+                    }
+                    catch { /* ignore */ }
+                }
+                const sendPromise = this._transport?.send({ jsonrpc: '2.0', id: request.id, result });
+                if (request.method === 'initialize') {
+                    (0, handshakeManager_1.initFrameLog)('dispatcher_before_send', { id: request.id });
+                    (sendPromise?.then?.(() => {
+                        (0, handshakeManager_1.initFrameLog)('dispatcher_send_resolved', { id: request.id });
+                        server.__initResponseSent = true;
+                        setTimeout(() => (0, handshakeManager_1.emitReadyGlobal)(server, 'transport-send-hook'), 0);
+                    }))?.catch(() => { });
+                }
+                return sendPromise;
+            }, (error) => {
+                if (startedAt !== undefined) {
+                    try {
+                        const dur = Date.now() - startedAt;
+                        const category = categorizeRequest(request);
+                        if (category === 'health' || category === 'meta' || category === 'metrics' || category === 'init') {
+                            __diagQueueDepth = Math.max(0, __diagQueueDepth - 1);
+                            process.stderr.write(`[diag] ${Date.now()} rq_error method=${request.method} cat=${category} id=${request.id} dur_ms=${dur} qdepth=${__diagQueueDepth}\n`);
+                            try {
+                                server.__activeDiagRequests?.delete(request.id);
+                            }
+                            catch { /* ignore */ }
+                        }
+                    }
+                    catch { /* ignore */ }
+                }
+                if (abortController.signal.aborted) {
+                    try {
+                        if ((0, runtimeConfig_1.getRuntimeConfig)().logging.verbose)
+                            process.stderr.write(`[rpc] aborted-error-path method=${request.method} id=${request.id}\n`);
+                    }
+                    catch { /* ignore */ }
+                }
+                // Robust semantic error preservation: search multiple nests for a JSON-RPC code/message
+                let errCode = error?.code;
+                if (!Number.isSafeInteger(errCode))
+                    errCode = error?.data?.code;
+                if (!Number.isSafeInteger(errCode))
+                    errCode = error?.original?.code;
+                if (!Number.isSafeInteger(errCode))
+                    errCode = error?.cause?.code;
+                if (!Number.isSafeInteger(errCode))
+                    errCode = error?.error?.code;
+                const rawBeforeDeep = errCode;
+                if (!Number.isSafeInteger(errCode) || errCode === -32603) {
+                    const deep = deepScan(error);
+                    if (Number.isSafeInteger(deep))
+                        errCode = deep;
+                }
+                const safeCode = Number.isSafeInteger(errCode) ? errCode : undefined;
+                let errMessage = error?.message;
+                if (!errMessage)
+                    errMessage = error?.data?.message;
+                if (!errMessage)
+                    errMessage = error?.original?.message;
+                if (!errMessage)
+                    errMessage = error?.cause?.message;
+                if (!errMessage)
+                    errMessage = error?.error?.message;
+                if (typeof errMessage !== 'string' || !errMessage.trim())
+                    errMessage = 'Internal error';
+                let data = error?.data;
+                if (data && typeof data === 'object') {
+                    if (typeof data.message !== 'string')
+                        data = { ...data, message: errMessage };
+                }
+                else if (error && typeof error === 'object') {
+                    data = { message: errMessage, ...(error.method ? { method: error.method } : {}) };
+                }
+                let finalCode = (safeCode !== undefined) ? safeCode : -32603;
+                if (finalCode === -32603 && data && typeof data === 'object') {
+                    try {
+                        const reason = data.reason || data.data?.reason;
+                        if (reason === 'missing_action')
+                            finalCode = -32602;
+                        else if (reason === 'unknown_action' || reason === 'mutation_disabled' || reason === 'unknown_handler')
+                            finalCode = -32601;
+                    }
+                    catch { /* ignore */ }
+                }
+                try {
+                    if ((0, runtimeConfig_1.getRuntimeConfig)().logging.verbose) {
+                        const before = Number.isSafeInteger(rawBeforeDeep) ? rawBeforeDeep : 'n/a';
+                        if ((before === 'n/a' || before === -32603) && (finalCode === -32601 || finalCode === -32602)) {
+                            const reasonHint = data?.reason || data?.data?.reason;
+                            process.stderr.write(`[rpc] deep_recover_semantic code=${finalCode} from=${before} reasonHint=${reasonHint || ''}\n`);
+                        }
+                    }
+                }
+                catch { /* ignore */ }
+                try {
+                    if ((0, runtimeConfig_1.getRuntimeConfig)().logging.verbose)
+                        process.stderr.write(`[rpc] response method=${request.method} id=${request.id} error=${errMessage} code=${finalCode}\n`);
+                }
+                catch { /* ignore */ }
+                return this._transport?.send({ jsonrpc: '2.0', id: request.id, error: { code: finalCode, message: errMessage, data } });
+            })
+                .catch(() => { })
+                .finally(() => { this._requestHandlerAbortControllers.delete(request.id); });
+        };
+        // Attach wrapper to BOTH potential internal symbols to guarantee interception.
+        server._onRequest = wrapped;
+        server._onrequest = wrapped;
+        server.__dispatcherOverrideActive = true;
+        try {
+            if ((0, runtimeConfig_1.getRuntimeConfig)().trace.has('healthMixed'))
+                process.stderr.write(`[diag] ${Date.now()} dispatcher_override applied props=${[existingCamel ? '_onRequest(original)' : '', existingLower ? '_onrequest(original)' : ''].filter(Boolean).join(',') || 'none'}\n`);
+        }
+        catch { /* ignore */ }
+        // Starvation watchdog
+        if ((0, runtimeConfig_1.getRuntimeConfig)().trace.has('healthMixed') && !server.__starvationWatchdogStarted) {
+            server.__starvationWatchdogStarted = true;
+            let ticks = 0;
+            const iv = setInterval(() => {
+                try {
+                    ticks++;
+                    const active = server.__activeDiagRequests;
+                    const firstH = server.__healthId1EnqueueAt;
+                    if (active && active.size) {
+                        const pending = Array.from(active.values()).map((r) => ({ id: r.id, cat: r.cat, age: Date.now() - r.start })).sort((a, b) => a.id - b.id).slice(0, 12);
+                        const hasHealth1 = !!active.get?.(1);
+                        if (hasHealth1 || (firstH && Date.now() - firstH > 40)) {
+                            process.stderr.write(`[diag] ${Date.now()} starvation_watchdog tick=${ticks} pending=${pending.length} details=${JSON.stringify(pending)} firstHealthAge=${firstH ? Date.now() - firstH : -1} hasHealth1=${hasHealth1}\n`);
+                        }
+                        if (!hasHealth1 && firstH && Date.now() - firstH > 400) {
+                            process.stderr.write(`[diag] ${Date.now()} starvation_watchdog_health1_missing age=${Date.now() - firstH}\n`);
+                        }
+                    }
+                    if (ticks > 40 || (server.__activeDiagRequests && !server.__activeDiagRequests.get(1))) {
+                        clearInterval(iv);
+                    }
+                }
+                catch { /* ignore */ }
+            }, 25);
+            iv.unref?.();
+        }
+    }
+    else if ((0, runtimeConfig_1.getRuntimeConfig)().trace.has('healthMixed')) {
+        try {
+            process.stderr.write(`[diag] ${Date.now()} dispatcher_override_skipped no_original_handler_found`);
+        }
+        catch { /* ignore */ }
+    }
+    // Enumerate server properties once for debugging missing override
+    try {
+        if ((0, runtimeConfig_1.getRuntimeConfig)().trace.has('healthMixed')) {
+            const props = Object.getOwnPropertyNames(server).filter(p => /_on|request|handler/i.test(p)).slice(0, 60);
+            process.stderr.write(`[diag] ${Date.now()} server_props ${props.join(',')}\n`);
+        }
+    }
+    catch { /* ignore */ }
+}
+/**
+ * Wrap transport.send to detect initialize response flush and emit ready.
+ */
+function wrapTransportSend(server, transport) {
+    try {
+        const origSend = transport?.send?.bind(transport);
+        if (origSend && !transport.__wrappedForReady) {
+            transport.__wrappedForReady = true;
+            transport.send = (msg) => {
+                let isInitResult = false;
+                try {
+                    isInitResult = !!(msg && typeof msg === 'object' && 'id' in msg && msg.result && msg.result.protocolVersion);
+                }
+                catch { /* ignore */ }
+                const sendPromise = origSend(msg);
+                // Fallback completion / error logging if dispatcher override not active
+                try {
+                    if ((0, runtimeConfig_1.getRuntimeConfig)().trace.has('healthMixed') && !server.__dispatcherOverrideActive && msg && typeof msg === 'object' && Object.prototype.hasOwnProperty.call(msg, 'id')) {
+                        const map = server.__diagRQMap;
+                        if (map && map.has(msg.id)) {
+                            const rec = map.get(msg.id);
+                            map.delete(msg.id);
+                            server.__diagQueueDepthSniff = Math.max(0, server.__diagQueueDepthSniff - 1);
+                            const kind = msg.error ? 'rq_error' : 'rq_complete';
+                            const dur = Date.now() - rec.start;
+                            process.stderr.write(`[diag] ${Date.now()} ${kind} method=${rec.method} cat=${rec.cat} id=${msg.id} dur_ms=${dur} qdepth=${server.__diagQueueDepthSniff} src=sniff-send\n`);
+                        }
+                    }
+                }
+                catch { /* ignore */ }
+                if (isInitResult && !server.__readyNotified) {
+                    server.__sawInitializeRequest = true;
+                    (0, handshakeManager_1.initFrameLog)('transport_detect_init_result', { id: msg.id });
+                    sendPromise?.then?.(() => {
+                        (0, handshakeManager_1.initFrameLog)('transport_send_resolved', { id: msg.id });
+                        server.__initResponseSent = true;
+                        setTimeout(() => (0, handshakeManager_1.emitReadyGlobal)(server, 'transport-send-hook-dynamic'), 0);
+                    })?.catch?.(() => { });
+                }
+                return sendPromise;
+            };
+        }
+    }
+    catch { /* ignore wrapper errors */ }
+}
+/**
+ * Explicit keepalive to avoid premature process exit before first client request.
+ * @param label - Optional label for diagnostic log messages (e.g. 'secondary')
+ */
+function setupKeepalive(label = '') {
+    try {
+        if (process.stdin.readable)
+            process.stdin.resume();
+        process.stdin.on('data', () => { }); // no-op to anchor listener
+        const ka = setInterval(() => { }, 10_000);
+        ka.unref?.();
+        if ((0, runtimeConfig_1.getRuntimeConfig)().logging.diagnostics) {
+            const prefix = label ? ` (${label})` : '';
+            const stdinListenerCount = process.stdin.listenerCount('data');
+            try {
+                process.stderr.write(`[transport-init]${prefix} keepalive setup complete stdin.dataListeners=${stdinListenerCount}\n`);
+            }
+            catch { /* ignore */ }
+        }
+    }
+    catch { /* ignore */ }
+}

package/dist/services/atomicFs.d.ts

@@ -0,0 +1,22 @@
+/**
+ * Atomically write JSON to disk with robust retry semantics for shared index scenarios.
+ *
+ * Rationale:
+ *  - Multiple Index Server processes may share the same instructions directory.
+ *  - On Windows / network filesystems, transient EPERM / EBUSY / EACCES can occur during rename
+ *    when virus scanners, indexers or another process have the destination briefly open.
+ *  - We mitigate by:
+ *      1. Writing content to a unique temp file.
+ *      2. Attempting fs.renameSync (atomic on same volume) with retry/backoff.
+ *      3. Falling back to a direct fs.writeFileSync(dest, data) on final attempt if rename keeps failing
+ *         specifically due to transient lock codes.
+ *  - No file descriptors are intentionally left open; synchronous methods close before returning.
+ *
+ * Configuration (via runtime config / env consolidation):
+ *  - atomicFs.retries (INDEX_SERVER_ATOMIC_WRITE_RETRIES, default 5) : total attempts (initial + retries)
+ *  - atomicFs.backoffMs (INDEX_SERVER_ATOMIC_WRITE_BACKOFF_MS, default 10): initial backoff in ms (exponential with jitter)
+ * @param filePath - Absolute path to the destination file
+ * @param obj - Value to serialize as pretty-printed JSON
+ * @throws Will throw if all write/rename attempts are exhausted due to non-transient errors
+ */
+export declare function atomicWriteJson(filePath: string, obj: unknown): void;

package/dist/services/atomicFs.js

@@ -0,0 +1,103 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.atomicWriteJson = atomicWriteJson;
+const fs_1 = __importDefault(require("fs"));
+const path_1 = __importDefault(require("path"));
+const crypto_1 = __importDefault(require("crypto"));
+const runtimeConfig_1 = require("../config/runtimeConfig");
+/**
+ * Atomically write JSON to disk with robust retry semantics for shared index scenarios.
+ *
+ * Rationale:
+ *  - Multiple Index Server processes may share the same instructions directory.
+ *  - On Windows / network filesystems, transient EPERM / EBUSY / EACCES can occur during rename
+ *    when virus scanners, indexers or another process have the destination briefly open.
+ *  - We mitigate by:
+ *      1. Writing content to a unique temp file.
+ *      2. Attempting fs.renameSync (atomic on same volume) with retry/backoff.
+ *      3. Falling back to a direct fs.writeFileSync(dest, data) on final attempt if rename keeps failing
+ *         specifically due to transient lock codes.
+ *  - No file descriptors are intentionally left open; synchronous methods close before returning.
+ *
+ * Configuration (via runtime config / env consolidation):
+ *  - atomicFs.retries (INDEX_SERVER_ATOMIC_WRITE_RETRIES, default 5) : total attempts (initial + retries)
+ *  - atomicFs.backoffMs (INDEX_SERVER_ATOMIC_WRITE_BACKOFF_MS, default 10): initial backoff in ms (exponential with jitter)
+ * @param filePath - Absolute path to the destination file
+ * @param obj - Value to serialize as pretty-printed JSON
+ * @throws Will throw if all write/rename attempts are exhausted due to non-transient errors
+ */
+function atomicWriteJson(filePath, obj) {
+    const dir = path_1.default.dirname(filePath);
+    if (!fs_1.default.existsSync(dir))
+        fs_1.default.mkdirSync(dir, { recursive: true });
+    const data = JSON.stringify(obj, null, 2);
+    const atomicConfig = (0, runtimeConfig_1.getRuntimeConfig)().atomicFs;
+    const maxAttempts = Math.max(1, atomicConfig.retries);
+    const baseBackoff = Math.max(1, atomicConfig.backoffMs);
+    let lastErr = null;
+    for (let attempt = 1; attempt <= maxAttempts; attempt++) {
+        const tmp = path_1.default.join(dir, `.${path_1.default.basename(filePath)}.${crypto_1.default.randomBytes(6).toString('hex')}.tmp`);
+        try {
+            fs_1.default.writeFileSync(tmp, data, 'utf8');
+            try {
+                fs_1.default.renameSync(tmp, filePath);
+                return; // success
+            }
+            catch (renameErr) {
+                // If rename failed, decide whether to retry
+                const code = renameErr.code;
+                const transient = code === 'EPERM' || code === 'EBUSY' || code === 'EACCES' || code === 'ENOENT';
+                if (!transient || attempt === maxAttempts) {
+                    // On final attempt we do NOT fallback to direct write to preserve atomic semantics; propagate.
+                    lastErr = renameErr;
+                    try {
+                        if (fs_1.default.existsSync(tmp))
+                            fs_1.default.unlinkSync(tmp);
+                    }
+                    catch { /* ignore */ }
+                    break;
+                }
+                lastErr = renameErr;
+                try {
+                    if (fs_1.default.existsSync(tmp))
+                        fs_1.default.unlinkSync(tmp);
+                }
+                catch { /* ignore */ }
+                // Backoff (exponential + jitter)
+                const sleepMs = baseBackoff * Math.pow(2, attempt - 1) + Math.floor(Math.random() * baseBackoff);
+                const start = Date.now();
+                while (Date.now() - start < sleepMs) { /* busy-wait tiny backoff (short durations) */ }
+                continue; // retry loop
+            }
+        }
+        catch (writeErr) {
+            const code = writeErr.code;
+            const transient = code === 'EPERM' || code === 'EBUSY' || code === 'EACCES';
+            if (!transient || attempt === maxAttempts) {
+                lastErr = writeErr;
+                try {
+                    if (fs_1.default.existsSync(tmp))
+                        fs_1.default.unlinkSync(tmp);
+                }
+                catch { /* ignore */ }
+                break;
+            }
+            lastErr = writeErr;
+            try {
+                if (fs_1.default.existsSync(tmp))
+                    fs_1.default.unlinkSync(tmp);
+            }
+            catch { /* ignore */ }
+            const sleepMs = baseBackoff * Math.pow(2, attempt - 1) + Math.floor(Math.random() * baseBackoff);
+            const start = Date.now();
+            while (Date.now() - start < sleepMs) { /* busy-wait */ }
+            continue;
+        }
+    }
+    // Propagate final error after exhausting attempts
+    const err = lastErr instanceof Error ? lastErr : new Error('atomicWriteJson failed');
+    throw err;
+}

package/dist/services/auditLog.d.ts

@@ -0,0 +1,38 @@
+/** Run a function with a correlation ID accessible to all logAudit() calls within. */
+export declare function runWithCorrelation<T>(correlationId: string, fn: () => T): T;
+/** Get the current correlation ID from the async context (if any). */
+export declare function getCurrentCorrelationId(): string | undefined;
+/** Reset the cached audit log path, forcing re-resolution on next write. */
+export declare function resetAuditLogCache(): void;
+export type AuditKind = 'mutation' | 'read' | 'http';
+export interface AuditEntry {
+    ts: string;
+    kind: AuditKind;
+    action: string;
+    ids?: string[];
+    meta?: Record<string, unknown>;
+}
+/**
+ * Append an entry to the audit log file. Silent no-op when logging is disabled.
+ * @param action - Tool or operation name being recorded
+ * @param ids - Instruction IDs affected by this operation (if any)
+ * @param meta - Lightweight result summary (counts, flags, etc.)
+ * @param kind - Entry classification; defaults to `'mutation'`
+ */
+export declare function logAudit(action: string, ids?: string[] | string, meta?: Record<string, unknown>, kind?: AuditKind): void;
+/**
+ * Log a tool invocation to the audit trail. Called from the registry wrapper
+ * so ALL tool calls (reads + mutations) are captured automatically.
+ */
+export declare function logToolAudit(toolName: string, success: boolean, durationMs: number, correlationId?: string, errorType?: string): void;
+/**
+ * Log an HTTP request to the audit trail. Called from dashboard middleware
+ * so all API requests are captured with client IP and user-agent.
+ */
+export declare function logHttpAudit(method: string, route: string, statusCode: number, durationMs: number, clientIp?: string, userAgent?: string): void;
+/**
+ * Read the most recent audit log entries from disk.
+ * @param limit - Maximum number of lines to return from the tail of the file (default 1000)
+ * @returns Parsed audit entries, or an empty array if logging is disabled or the file is missing
+ */
+export declare function readAuditEntries(limit?: number): AuditEntry[];