@softerist/heuristic-mcp 3.2.4 → 3.2.6

package/features/find-similar-code.js

@@ -1,6 +1,24 @@
 import path from 'path';
 import { dotSimilarity, smartChunk, estimateTokens, getModelTokenLimit } from '../lib/utils.js';
 
+function alignQueryVectorDimension(vector, targetDim) {
+  if (!(vector instanceof Float32Array)) {
+    vector = new Float32Array(vector);
+  }
+  if (!Number.isInteger(targetDim) || targetDim <= 0 || vector.length <= targetDim) {
+    return vector;
+  }
+
+  const sliced = vector.slice(0, targetDim);
+  let mag = 0;
+  for (let i = 0; i < sliced.length; i += 1) mag += sliced[i] * sliced[i];
+  mag = Math.sqrt(mag);
+  if (mag > 0) {
+    for (let i = 0; i < sliced.length; i += 1) sliced[i] /= mag;
+  }
+  return sliced;
+}
+
 export class FindSimilarCode {
   constructor(embedder, cache, config) {
     this.embedder = embedder;
@@ -84,6 +102,7 @@ export class FindSimilarCode {
           } catch {}
         }
       }
+      codeVector = alignQueryVectorDimension(codeVector, this.config.embeddingDimension);
 
       let candidates = vectorStore;
       let usedAnn = false;

package/features/hybrid-search.js

@@ -9,6 +9,24 @@ import {
   PARTIAL_MATCH_BOOST,
 } from '../lib/constants.js';
 
+function alignQueryVectorDimension(vector, targetDim) {
+  if (!(vector instanceof Float32Array)) {
+    vector = new Float32Array(vector);
+  }
+  if (!Number.isInteger(targetDim) || targetDim <= 0 || vector.length <= targetDim) {
+    return vector;
+  }
+
+  const sliced = vector.slice(0, targetDim);
+  let mag = 0;
+  for (let i = 0; i < sliced.length; i += 1) mag += sliced[i] * sliced[i];
+  mag = Math.sqrt(mag);
+  if (mag > 0) {
+    for (let i = 0; i < sliced.length; i += 1) sliced[i] /= mag;
+  }
+  return sliced;
+}
+
 export class HybridSearch {
   constructor(embedder, cache, config) {
     this.embedder = embedder;
@@ -134,6 +152,7 @@ export class HybridSearch {
           }
         }
       }
+      queryVector = alignQueryVectorDimension(queryVector, this.config.embeddingDimension);
 
       let candidateIndices = null;
       let usedAnn = false;
@@ -336,7 +355,7 @@ export class HybridSearch {
             for (let k = 0; k < queryWordCount; k++) {
               if (lowerContent.includes(queryWords[k])) matchedWords++;
             }
-            chunk.score += (matchedWords / queryWordCount) * 0.3;
+            chunk.score += (matchedWords / queryWordCount) * PARTIAL_MATCH_BOOST;
           }
 
           if (chunk.content === undefined) {

package/features/index-codebase.js

@@ -2769,7 +2769,13 @@ export class CodebaseIndexer {
         lastCheckpointIntervalMs: checkpointIntervalMs,
         lastCheckpointSaves: checkpointSaveCount,
       });
-      await this.cache.save({ throwOnError: true });
+      try {
+        await this.cache.save({ throwOnError: true });
+      } catch (error) {
+        const message = error instanceof Error ? error.message : String(error);
+        console.error(`[Indexer] Final cache save failed after embedding pass: ${message}`);
+        throw error;
+      }
 
       this.sendProgress(
         100,

package/features/set-workspace.js

@@ -167,6 +167,9 @@ export class SetWorkspaceFeature {
 
     if (this.cache && typeof this.cache.load === 'function') {
       try {
+        if (typeof this.cache.clearInMemoryState === 'function') {
+          this.cache.clearInMemoryState();
+        }
         if (this.config.vectorStoreFormat === 'binary') {
           await cleanupStaleBinaryArtifacts(newCacheDir);
         }
@@ -201,11 +204,12 @@ export class SetWorkspaceFeature {
 }
 
 export function createHandleToolCall(featureInstance) {
-  return async (request) => {
+  return async (request, instance) => {
+    const activeInstance = instance ?? featureInstance;
     const args = request.params?.arguments || {};
     const { workspacePath, reindex } = args;
 
-    const result = await featureInstance.execute({
+    const result = await activeInstance.execute({
       workspacePath,
       reindex: reindex !== false,
     });

package/index.js

@@ -16,9 +16,6 @@ async function getTransformers() {
     if (transformersModule?.env) {
       transformersModule.env.cacheDir = path.join(getGlobalCacheDir(), 'xenova');
     }
-    if (transformersModule?.env) {
-      transformersModule.env.cacheDir = path.join(getGlobalCacheDir(), 'xenova');
-    }
   }
   return transformersModule;
 }
@@ -50,6 +47,7 @@ import {
   registerSignalHandlers,
   setupPidFile,
   acquireWorkspaceLock,
+  releaseWorkspaceLock,
   stopOtherHeuristicServers,
 } from './lib/server-lifecycle.js';
 
@@ -79,6 +77,13 @@ import {
 } from './lib/constants.js';
 const PID_FILE_NAME = '.heuristic-mcp.pid';
 
+function isTestRuntime() {
+  return (
+    process.env.VITEST === 'true' ||
+    process.env.NODE_ENV === 'test'
+  );
+}
+
 async function readLogTail(logPath, maxLines = 2000) {
   const data = await fs.readFile(logPath, 'utf-8');
   if (!data) return [];
@@ -134,6 +139,36 @@ async function printMemorySnapshot(workspaceDir) {
   return true;
 }
 
+async function flushLogsSafely(options) {
+  if (typeof flushLogs !== 'function') {
+    console.warn('[Logs] flushLogs helper is unavailable; skipping log flush.');
+    return;
+  }
+
+  try {
+    await flushLogs(options);
+  } catch (error) {
+    const message = error instanceof Error ? error.message : String(error);
+    console.warn(`[Logs] Failed to flush logs: ${message}`);
+  }
+}
+
+function assertCacheContract(cacheInstance) {
+  const requiredMethods = [
+    'load',
+    'save',
+    'consumeAutoReindex',
+    'clearInMemoryState',
+    'getStoreSize',
+  ];
+  const missing = requiredMethods.filter((name) => typeof cacheInstance?.[name] !== 'function');
+  if (missing.length > 0) {
+    throw new Error(
+      `[Server] Cache implementation contract violation: missing method(s): ${missing.join(', ')}`
+    );
+  }
+}
+
 let embedder = null;
 let unloadMainEmbedder = null;
 let cache = null;
@@ -150,6 +185,10 @@ let setWorkspaceFeatureInstance = null;
 let autoWorkspaceSwitchPromise = null;
 let rootsCapabilitySupported = null;
 let rootsProbeInFlight = null;
+let lastRootsProbeTime = 0;
+let keepAliveTimer = null;
+let stdioShutdownHandlers = null;
+const ROOTS_PROBE_COOLDOWN_MS = 2000;
 const WORKSPACE_BOUND_TOOL_NAMES = new Set([
   'a_semantic_search',
   'b_index_codebase',
@@ -202,11 +241,22 @@ function formatCrashDetail(detail) {
   }
 }
 
+function isBrokenPipeError(detail) {
+  return Boolean(detail && typeof detail === 'object' && detail.code === 'EPIPE');
+}
+
 function isCrashShutdownReason(reason) {
   const normalized = String(reason || '').toLowerCase();
   return normalized.includes('uncaughtexception') || normalized.includes('unhandledrejection');
 }
 
+function getShutdownExitCode(reason) {
+  const normalized = String(reason || '').trim().toUpperCase();
+  if (normalized === 'SIGINT') return 130;
+  if (normalized === 'SIGTERM') return 143;
+  return isCrashShutdownReason(reason) ? 1 : 0;
+}
+
 function registerProcessDiagnostics({ isServerMode, requestShutdown, getShutdownReason }) {
   if (!isServerMode) return;
 
@@ -223,6 +273,10 @@ function registerProcessDiagnostics({ isServerMode, requestShutdown, getShutdown
   let fatalHandled = false;
   const handleFatalError = (reason, detail) => {
     if (fatalHandled) return;
+    if (isBrokenPipeError(detail)) {
+      requestShutdown('stdio-epipe');
+      return;
+    }
     fatalHandled = true;
     console.error(`[Server] Fatal ${reason}: ${formatCrashDetail(detail)}`);
     requestShutdown(reason);
@@ -241,6 +295,44 @@ function registerProcessDiagnostics({ isServerMode, requestShutdown, getShutdown
   });
 }
 
+function registerStdioShutdownHandlers(requestShutdown) {
+  if (stdioShutdownHandlers) return;
+
+  const onStdinEnd = () => requestShutdown('stdin-end');
+  const onStdinClose = () => requestShutdown('stdin-close');
+  const onStdoutError = (err) => {
+    if (err?.code === 'EPIPE') {
+      requestShutdown('stdout-epipe');
+    }
+  };
+  const onStderrError = (err) => {
+    if (err?.code === 'EPIPE') {
+      requestShutdown('stderr-epipe');
+    }
+  };
+
+  process.stdin?.on?.('end', onStdinEnd);
+  process.stdin?.on?.('close', onStdinClose);
+  process.stdout?.on?.('error', onStdoutError);
+  process.stderr?.on?.('error', onStderrError);
+
+  stdioShutdownHandlers = {
+    onStdinEnd,
+    onStdinClose,
+    onStdoutError,
+    onStderrError,
+  };
+}
+
+function unregisterStdioShutdownHandlers() {
+  if (!stdioShutdownHandlers) return;
+  process.stdin?.off?.('end', stdioShutdownHandlers.onStdinEnd);
+  process.stdin?.off?.('close', stdioShutdownHandlers.onStdinClose);
+  process.stdout?.off?.('error', stdioShutdownHandlers.onStdoutError);
+  process.stderr?.off?.('error', stdioShutdownHandlers.onStderrError);
+  stdioShutdownHandlers = null;
+}
+
 async function resolveWorkspaceFromEnvValue(rawValue) {
   if (!rawValue || rawValue.includes('${')) return null;
   const resolved = path.resolve(rawValue);
@@ -460,12 +552,15 @@ async function maybeAutoSwitchWorkspaceToPath(
 
   if (autoWorkspaceSwitchPromise) {
     await autoWorkspaceSwitchPromise;
-    return;
+    const currentNow = normalizePathForCompare(config.searchDirectory);
+    const targetNow = normalizePathForCompare(targetWorkspacePath);
+    if (targetNow === currentNow) return;
   }
 
-  autoWorkspaceSwitchPromise = (async () => {
+  const switchPromise = (async () => {
+    const latestWorkspace = normalizePathForCompare(config.searchDirectory);
     console.info(
-      `[Server] Auto-switching workspace from ${currentWorkspace} to ${targetWorkspacePath} (${source || 'auto'})`
+      `[Server] Auto-switching workspace from ${latestWorkspace} to ${targetWorkspacePath} (${source || 'auto'})`
     );
     const result = await setWorkspaceFeatureInstance.execute({
       workspacePath: targetWorkspacePath,
@@ -477,11 +572,14 @@ async function maybeAutoSwitchWorkspaceToPath(
     }
     trustWorkspacePath(targetWorkspacePath);
   })();
+  autoWorkspaceSwitchPromise = switchPromise;
 
   try {
-    await autoWorkspaceSwitchPromise;
+    await switchPromise;
   } finally {
-    autoWorkspaceSwitchPromise = null;
+    if (autoWorkspaceSwitchPromise === switchPromise) {
+      autoWorkspaceSwitchPromise = null;
+    }
   }
 }
 
@@ -494,6 +592,9 @@ async function maybeAutoSwitchWorkspaceFromRoots(request) {
   if (rootsProbeInFlight) {
     return await rootsProbeInFlight;
   }
+  const now = Date.now();
+  if (now - lastRootsProbeTime < ROOTS_PROBE_COOLDOWN_MS) return null;
+  lastRootsProbeTime = now;
 
   rootsProbeInFlight = (async () => {
     const rootWorkspace = await detectWorkspaceFromRoots({ quiet: true });
@@ -566,7 +667,7 @@ async function initialize(workspaceDir) {
     }
   }
 
-  const isTest = Boolean(process.env.VITEST || process.env.VITEST_WORKER_ID);
+  const isTest = isTestRuntime();
   if (config.enableExplicitGc && typeof global.gc !== 'function' && !isTest) {
     console.warn(
       '[Server] enableExplicitGc=true but this process was not started with --expose-gc; continuing with explicit GC disabled.'
@@ -820,6 +921,7 @@ async function initialize(workspaceDir) {
   }
 
   cache = new EmbeddingsCache(config);
+  assertCacheContract(cache);
   console.info(`[Server] Cache directory: ${config.cacheDirectory}`);
 
   indexer = new CodebaseIndexer(embedder, cache, config, server);
@@ -865,7 +967,7 @@ async function initialize(workspaceDir) {
         );
       } else {
         console.warn(
-          `[Server] Cache corruption detected while ${context}. This server is secondary read-only and cannot re-index. Reload the IDE window for this workspace or use the primary instance to rebuild the cache.`
+          `[Server] Cache corruption detected while ${context}. This server is secondary read-only and cannot re-index. Restart the MCP client session for this workspace or use the primary instance to rebuild the cache.`
         );
       }
       return true;
@@ -936,7 +1038,8 @@ async function initialize(workspaceDir) {
           context: 'loading cache in secondary read-only mode',
           canReindex: false,
         });
-        if (cache.getStoreSize() === 0) {
+        const storeSize = cache.getStoreSize();
+        if (storeSize === 0) {
           await tryAutoAttachWorkspaceCache('secondary-empty-cache', { canReindex: false });
         }
         if (config.verbose) {
@@ -1107,7 +1210,7 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
           content: [
             {
               type: 'text',
-              text: `Attached cache for ${normalizedPath}, but it is corrupt. This secondary read-only instance cannot rebuild it. Reload the IDE window for this workspace or run indexing from the primary instance.`,
+              text: `Attached cache for ${normalizedPath}, but it is corrupt. This secondary read-only instance cannot rebuild it. Restart the MCP client session for this workspace or run indexing from the primary instance.`,
             },
           ],
           isError: true,
@@ -1217,10 +1320,15 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
 
       const searchTools = ['a_semantic_search', 'd_find_similar_code'];
       if (config.unloadModelAfterSearch && searchTools.includes(toolDef.name)) {
-        setImmediate(async () => {
-          if (typeof unloadMainEmbedder === 'function') {
-            await unloadMainEmbedder();
-          }
+        setImmediate(() => {
+          const unloadFn = unloadMainEmbedder;
+          if (typeof unloadFn !== 'function') return;
+          void Promise.resolve()
+            .then(() => unloadFn())
+            .catch((err) => {
+              const message = err instanceof Error ? err.message : String(err);
+              console.warn(`[Server] Post-search model unload failed: ${message}`);
+            });
         });
       }
 
@@ -1270,13 +1378,14 @@ export async function main(argv = process.argv) {
     console.info(`[Server] Shutdown requested (${reason}).`);
     void gracefulShutdown(reason);
   };
+  const isTestEnv = isTestRuntime();
   registerProcessDiagnostics({
     isServerMode,
     requestShutdown,
     getShutdownReason: () => shutdownReason,
   });
 
-  if (isServerMode && !(process.env.VITEST === 'true' || process.env.NODE_ENV === 'test')) {
+  if (isServerMode && !isTestEnv) {
     enableStderrOnlyLogging();
   }
   if (wantsVersion) {
@@ -1403,41 +1512,37 @@ export async function main(argv = process.argv) {
 
   registerSignalHandlers(requestShutdown);
 
-  const detectedRootPromise = new Promise((resolve) => {
-    const HANDSHAKE_TIMEOUT_MS = 1000;
-    let settled = false;
-    const resolveOnce = (value) => {
-      if (settled) return;
-      settled = true;
-      resolve(value);
-    };
+  const detectedRootPromise = isTestEnv
+    ? Promise.resolve(null)
+    : new Promise((resolve) => {
+        const HANDSHAKE_TIMEOUT_MS = 1000;
+        let settled = false;
+        const resolveOnce = (value) => {
+          if (settled) return;
+          settled = true;
+          resolve(value);
+        };
 
-    const timer = setTimeout(() => {
-      console.warn(
-        `[Server] MCP handshake timed out after ${HANDSHAKE_TIMEOUT_MS}ms, proceeding without roots.`
-      );
-      resolveOnce(null);
-    }, HANDSHAKE_TIMEOUT_MS);
-
-    server.oninitialized = async () => {
-      clearTimeout(timer);
-      console.info('[Server] MCP handshake complete.');
-      const root = await detectWorkspaceFromRoots();
-      resolveOnce(root);
-    };
-  });
+        const timer = setTimeout(() => {
+          console.warn(
+            `[Server] MCP handshake timed out after ${HANDSHAKE_TIMEOUT_MS}ms, proceeding without roots.`
+          );
+          resolveOnce(null);
+        }, HANDSHAKE_TIMEOUT_MS);
+
+        server.oninitialized = async () => {
+          clearTimeout(timer);
+          console.info('[Server] MCP handshake complete.');
+          const root = await detectWorkspaceFromRoots();
+          resolveOnce(root);
+        };
+      });
 
   const transport = new StdioServerTransport();
   await server.connect(transport);
   console.info('[Server] MCP transport connected.');
   if (isServerMode) {
-    process.stdin?.on?.('end', () => requestShutdown('stdin-end'));
-    process.stdin?.on?.('close', () => requestShutdown('stdin-close'));
-    process.stdout?.on?.('error', (err) => {
-      if (err?.code === 'EPIPE') {
-        requestShutdown('stdout-epipe');
-      }
-    });
+    registerStdioShutdownHandlers(requestShutdown);
   }
 
   const detectedRoot = await detectedRootPromise;
@@ -1446,28 +1551,28 @@ export async function main(argv = process.argv) {
   if (detectedRoot) {
     console.info(`[Server] Using workspace from MCP roots: ${detectedRoot}`);
   }
-  const initPromise = initialize(effectiveWorkspace);
-  const initWithResolve = initPromise
-    .then((result) => {
-      configReadyResolve();
-      return result;
-    })
-    .catch((err) => {
-      configInitError = err;
-      configReadyResolve();
-      throw err;
-    });
-  const { startBackgroundTasks } = await initWithResolve;
+  let startBackgroundTasks;
+  try {
+    const initResult = await initialize(effectiveWorkspace);
+    startBackgroundTasks = initResult.startBackgroundTasks;
+  } catch (err) {
+    configInitError = err;
+    configReadyResolve();
+    throw err;
+  }
 
   console.info('[Server] Heuristic MCP server started.');
 
-  void startBackgroundTasks().catch((err) => {
+  try {
+    await startBackgroundTasks();
+  } catch (err) {
     console.error(`[Server] Background task error: ${err.message}`);
-  });
+  }
+  configReadyResolve();
   // Keep-Alive mechanism: ensure the process stays alive even if StdioServerTransport
   // temporarily loses its active handle status or during complex async chains.
-  if (isServerMode) {
-    setInterval(() => {
+  if (isServerMode && !isTestEnv && !keepAliveTimer) {
+    keepAliveTimer = setInterval(() => {
       // Logic to keep event loop active.
       // We don't need to do anything, just the presence of the timer is enough.
     }, SERVER_KEEP_ALIVE_INTERVAL_MS);
@@ -1478,7 +1583,14 @@ export async function main(argv = process.argv) {
 
 async function gracefulShutdown(signal) {
   console.info(`[Server] Received ${signal}, shutting down gracefully...`);
-  const exitCode = isCrashShutdownReason(signal) ? 1 : 0;
+  const exitCode = getShutdownExitCode(signal);
+
+  if (keepAliveTimer) {
+    clearInterval(keepAliveTimer);
+    keepAliveTimer = null;
+  }
+
+  unregisterStdioShutdownHandlers();
 
   const cleanupTasks = [];
 
@@ -1502,37 +1614,57 @@ async function gracefulShutdown(signal) {
   }
 
   if (cache) {
-    if (!workspaceLockAcquired) {
-      console.info('[Server] Secondary/fallback mode: skipping cache save.');
-    } else {
-      cleanupTasks.push(
-        cache
-          .save()
-          .then(() => console.info('[Server] Cache saved'))
-          .catch((err) => console.error(`[Server] Failed to save cache: ${err.message}`))
-      );
-    }
+    cleanupTasks.push(
+      (async () => {
+        if (!workspaceLockAcquired) {
+          console.info('[Server] Secondary/fallback mode: skipping cache save.');
+        } else {
+          await cache.save();
+          console.info('[Server] Cache saved');
+        }
+        if (typeof cache.close === 'function') {
+          await cache.close();
+        }
+      })().catch((err) => console.error(`[Server] Cache shutdown cleanup failed: ${err.message}`))
+    );
+  }
+
+  if (workspaceLockAcquired && config?.cacheDirectory) {
+    cleanupTasks.push(
+      releaseWorkspaceLock({ cacheDirectory: config.cacheDirectory }).catch((err) =>
+        console.warn(`[Server] Failed to release workspace lock: ${err.message}`)
+      )
+    );
   }
 
   await Promise.allSettled(cleanupTasks);
   console.info('[Server] Goodbye!');
-  await flushLogs({ close: true, timeoutMs: 1500 }).catch(() => {});
+  await flushLogsSafely({ close: true, timeoutMs: 1500 });
 
   setTimeout(() => process.exit(exitCode), 100);
 }
 
+function isLikelyCliEntrypoint(argvPath) {
+  const base = path.basename(argvPath || '').toLowerCase();
+  return (
+    base === 'heuristic-mcp' ||
+    base === 'heuristic-mcp.js' ||
+    base === 'heuristic-mcp.mjs' ||
+    base === 'heuristic-mcp.cjs' ||
+    base === 'heuristic-mcp.cmd'
+  );
+}
+
 const isMain =
   process.argv[1] &&
   (path.resolve(process.argv[1]).toLowerCase() === fileURLToPath(import.meta.url).toLowerCase() ||
-    process.argv[1].endsWith('heuristic-mcp') ||
-    process.argv[1].endsWith('heuristic-mcp.js') ||
-    path.basename(process.argv[1]) === 'index.js') &&
+    isLikelyCliEntrypoint(process.argv[1])) &&
   !(process.env.VITEST === 'true' || process.env.NODE_ENV === 'test');
 
 if (isMain) {
   main().catch(async (err) => {
     console.error(err);
-    await flushLogs({ close: true, timeoutMs: 500 }).catch(() => {});
+    await flushLogsSafely({ close: true, timeoutMs: 500 });
     process.exit(1);
   });
 }

package/lib/cache.js

@@ -223,14 +223,7 @@ function normalizeFileHashEntry(entry) {
 }
 
 function serializeFileHashEntry(entry) {
-  if (!entry) return null;
-  if (typeof entry === 'string') return { hash: entry };
-  if (typeof entry !== 'object') return null;
-  if (typeof entry.hash !== 'string') return null;
-  const serialized = { hash: entry.hash };
-  if (Number.isFinite(entry.mtimeMs)) serialized.mtimeMs = entry.mtimeMs;
-  if (Number.isFinite(entry.size)) serialized.size = entry.size;
-  return serialized;
+  return normalizeFileHashEntry(entry);
 }
 
 function computeAnnCapacity(total, config) {
@@ -444,7 +437,7 @@ export class EmbeddingsCache {
     await Promise.race([
       waiterPromise,
       new Promise((resolve) => {
-        setTimeout(() => {
+        const timer = setTimeout(() => {
           if (!resolved) {
             resolved = true;
             timedOut = true;
@@ -454,6 +447,7 @@ export class EmbeddingsCache {
             resolve();
           }
         }, timeoutMs);
+        timer.unref?.();
       }),
     ]);
     if (timedOut) {
@@ -789,6 +783,7 @@ export class EmbeddingsCache {
             this._savePromise = null;
           });
       }, debounceMs);
+      this._saveTimer.unref?.();
     });
 
     return this._savePromise;
@@ -1528,7 +1523,11 @@ export class EmbeddingsCache {
     if (labels.length === 0) return [];
 
     const filtered = labels.filter(
-      (label) => Number.isInteger(label) && label >= 0 && label < this.vectorStore.length
+      (label) =>
+        Number.isInteger(label) &&
+        label >= 0 &&
+        label < this.vectorStore.length &&
+        Boolean(this.vectorStore[label])
     );
 
     return filtered;

package/lib/embed-query-process.js

@@ -13,6 +13,7 @@ let idleTimer = null;
 let currentConfig = null;
 let pendingRequests = [];
 let isProcessingRequest = false;
+let activeRequest = null;
 
 const DEFAULT_IDLE_TIMEOUT_MS = EMBEDDING_POOL_IDLE_TIMEOUT_MS;
 
@@ -43,36 +44,59 @@ function getOrCreateChild(config) {
   childReadline.on('line', (line) => {
     if (!line.trim()) return;
 
-    if (pendingRequests.length > 0) {
-      const { resolve, reject, startTime } = pendingRequests.shift();
-      try {
-        const result = JSON.parse(line);
-        const elapsed = ((Date.now() - startTime) / 1000).toFixed(2);
-
-        if (!result.results || result.results.length === 0) {
-          reject(new Error('Embedding child process returned no results'));
-          return;
-        }
-
-        const embResult = result.results[0];
-        if (!embResult.success) {
-          reject(new Error(`Embedding failed: ${embResult.error}`));
-          return;
-        }
-
-        const vector = new Float32Array(embResult.vector);
-
-        if (currentConfig?.verbose) {
-          console.info(`[Search] Query embedding (persistent child) completed in ${elapsed}s`);
-        }
-
-        resolve(vector);
-      } catch (err) {
-        reject(new Error(`Failed to parse embedding result: ${err.message}`));
-      } finally {
-        isProcessingRequest = false;
-        processNextRequest();
+    let result;
+    try {
+      result = JSON.parse(line);
+    } catch {
+      if (currentConfig?.verbose) {
+        console.warn('[EmbedPool] Ignoring non-JSON stdout from embedding child');
+      }
+      return;
+    }
+
+    if (!result || typeof result !== 'object' || !Object.prototype.hasOwnProperty.call(result, 'results')) {
+      if (currentConfig?.verbose) {
+        console.warn('[EmbedPool] Ignoring unexpected stdout payload from embedding child');
+      }
+      return;
+    }
+
+    if (!activeRequest) {
+      if (currentConfig?.verbose) {
+        console.warn('[EmbedPool] Received embedding response with no active request');
+      }
+      return;
+    }
+
+    const { resolve, reject, startTime } = activeRequest;
+    activeRequest = null;
+
+    try {
+      const elapsed = ((Date.now() - startTime) / 1000).toFixed(2);
+
+      if (!result.results || result.results.length === 0) {
+        reject(new Error('Embedding child process returned no results'));
+        return;
+      }
+
+      const embResult = result.results[0];
+      if (!embResult.success) {
+        reject(new Error(`Embedding failed: ${embResult.error}`));
+        return;
+      }
+
+      const vector = new Float32Array(embResult.vector);
+
+      if (currentConfig?.verbose) {
+        console.info(`[Search] Query embedding (persistent child) completed in ${elapsed}s`);
       }
+
+      resolve(vector);
+    } catch (err) {
+      reject(new Error(`Failed to parse embedding result: ${err.message}`));
+    } finally {
+      isProcessingRequest = false;
+      processNextRequest();
     }
   });
 
@@ -84,8 +108,14 @@ function getOrCreateChild(config) {
 
   persistentChild.on('error', (err) => {
     console.error(`[EmbedPool] Child process error: ${err.message}`);
+    const inflight = activeRequest;
     cleanupChild();
 
+    if (inflight) {
+      inflight.reject(new Error(`Child process error: ${err.message}`));
+      activeRequest = null;
+    }
+
     for (const { reject } of pendingRequests) {
       reject(new Error(`Child process error: ${err.message}`));
     }
@@ -96,8 +126,14 @@ function getOrCreateChild(config) {
     if (currentConfig?.verbose) {
       console.info(`[EmbedPool] Child process exited with code ${code}`);
     }
+    const inflight = activeRequest;
     cleanupChild();
 
+    if (inflight) {
+      inflight.reject(new Error(`Child process exited unexpectedly with code ${code}`));
+      activeRequest = null;
+    }
+
     for (const { reject } of pendingRequests) {
       reject(new Error(`Child process exited unexpectedly with code ${code}`));
     }
@@ -132,6 +168,9 @@ function resetIdleTimer(config) {
       shutdownChild();
     }
   }, timeout);
+  if (typeof idleTimer.unref === 'function') {
+    idleTimer.unref();
+  }
 }
 
 function cleanupChild() {
@@ -148,6 +187,15 @@ function cleanupChild() {
 }
 
 function shutdownChild() {
+  if (activeRequest) {
+    activeRequest.reject(new Error('Embedding pool shutdown requested'));
+    activeRequest = null;
+  }
+  for (const { reject } of pendingRequests) {
+    reject(new Error('Embedding pool shutdown requested'));
+  }
+  pendingRequests = [];
+
   if (persistentChild && !persistentChild.killed) {
     try {
       persistentChild.stdin.write(JSON.stringify({ type: 'shutdown' }) + '\n');
@@ -159,19 +207,21 @@ function shutdownChild() {
 }
 
 function processNextRequest() {
-  if (isProcessingRequest || pendingRequests.length === 0) return;
+  if (isProcessingRequest || activeRequest || pendingRequests.length === 0) return;
 
-  const request = pendingRequests[0];
+  const request = pendingRequests.shift();
   if (!request) return;
 
   isProcessingRequest = true;
+  activeRequest = request;
 
   try {
     const child = getOrCreateChild(request.config);
     child.stdin.write(JSON.stringify(request.payload) + '\n');
   } catch (err) {
-    const { reject } = pendingRequests.shift();
+    const { reject } = request;
     reject(err);
+    activeRequest = null;
     isProcessingRequest = false;
     processNextRequest();
   }

package/lib/embedding-worker.js

@@ -713,10 +713,11 @@ parentPort.on('message', async (message) => {
             maybeRunGc();
           }
 
+          const taskIndex = fileTasks.length;
           if (chunks.length > 0) {
             for (const c of chunks) {
               allPendingChunks.push({
-                fileIndex: i,
+                fileTaskIndex: taskIndex,
                 text: c.text,
                 startLine: c.startLine,
                 endLine: c.endLine,
@@ -847,7 +848,7 @@ parentPort.on('message', async (message) => {
 
       for (const chunkItem of allPendingChunks) {
         if (chunkItem.vectorBuffer) {
-          const task = fileTasks[chunkItem.fileIndex];
+          const task = fileTasks[chunkItem.fileTaskIndex];
           task.results.push({
             startLine: chunkItem.startLine,
             endLine: chunkItem.endLine,

package/lib/logging.js

@@ -4,23 +4,39 @@ import path from 'path';
 import util from 'util';
 
 let logStream = null;
+let stderrWritable = true;
 const originalConsole = {
-  log: console.info,
+  // eslint-disable-next-line no-console
+  log: console.log,
   warn: console.warn,
   error: console.error,
   info: console.info,
 };
 
+function isBrokenPipeError(error) {
+  return Boolean(error && typeof error === 'object' && error.code === 'EPIPE');
+}
+
+function writeToOriginalStderr(...args) {
+  if (!stderrWritable) return;
+  try {
+    originalConsole.error(...args);
+  } catch (error) {
+    if (isBrokenPipeError(error)) {
+      stderrWritable = false;
+      return;
+    }
+    throw error;
+  }
+}
+
 export function enableStderrOnlyLogging() {
-  const redirect = (...args) => originalConsole.error(...args);
+  const redirect = (...args) => writeToOriginalStderr(...args);
   // eslint-disable-next-line no-console
   console.log = redirect;
   console.info = redirect;
   console.warn = redirect;
   console.error = redirect;
-  // eslint-disable-next-line no-console
-  console.log = redirect;
-  console.info = redirect;
 }
 
 export async function setupFileLogging(config) {
@@ -49,10 +65,9 @@ export async function setupFileLogging(config) {
     };
 
     const wrap = (method, level) => {
-      const originalError = originalConsole.error;
       // eslint-disable-next-line no-console
       console[method] = (...args) => {
-        originalError(...args);
+        writeToOriginalStderr(...args);
         writeLine(level, args);
       };
     };
@@ -63,7 +78,7 @@ export async function setupFileLogging(config) {
     wrap('info', 'INFO');
 
     logStream.on('error', (err) => {
-      originalConsole.error(`[Logs] Failed to write log file: ${err.message}`);
+      writeToOriginalStderr(`[Logs] Failed to write log file: ${err.message}`);
     });
 
     process.on('exit', () => {
@@ -72,7 +87,7 @@ export async function setupFileLogging(config) {
 
     return logPath;
   } catch (err) {
-    originalConsole.error(`[Logs] Failed to initialize log file: ${err.message}`);
+    writeToOriginalStderr(`[Logs] Failed to initialize log file: ${err.message}`);
     return null;
   }
 }

package/lib/server-lifecycle.js

@@ -4,10 +4,54 @@ import path from 'path';
 import os from 'os';
 import { setTimeout as delay } from 'timers/promises';
 
+const pidFilesToCleanup = new Set();
+const workspaceLocksToCleanup = new Set();
+let pidExitCleanupRegistered = false;
+let workspaceLockExitCleanupRegistered = false;
+let registeredSignalHandlers = null;
+const LOCK_RETRY_BASE_DELAY_MS = 50;
+const LOCK_RETRY_MAX_DELAY_MS = 500;
+
 function isTestEnv() {
   return process.env.VITEST === 'true' || process.env.NODE_ENV === 'test';
 }
 
+function cleanupPidFilesOnExit() {
+  for (const pidPath of pidFilesToCleanup) {
+    try {
+      fsSync.unlinkSync(pidPath);
+    } catch {}
+  }
+}
+
+function registerPidFileCleanup(pidPath) {
+  if (!pidPath) return;
+  pidFilesToCleanup.add(pidPath);
+  if (pidExitCleanupRegistered) return;
+  process.on('exit', cleanupPidFilesOnExit);
+  pidExitCleanupRegistered = true;
+}
+
+function cleanupWorkspaceLocksOnExit() {
+  for (const lockPath of workspaceLocksToCleanup) {
+    try {
+      const raw = fsSync.readFileSync(lockPath, 'utf-8');
+      const current = JSON.parse(raw);
+      if (current && current.pid === process.pid) {
+        fsSync.unlinkSync(lockPath);
+      }
+    } catch {}
+  }
+}
+
+function registerWorkspaceLockCleanup(lockPath) {
+  if (!lockPath) return;
+  workspaceLocksToCleanup.add(lockPath);
+  if (workspaceLockExitCleanupRegistered) return;
+  process.on('exit', cleanupWorkspaceLocksOnExit);
+  workspaceLockExitCleanupRegistered = true;
+}
+
 function getPidFilePath({ pidFileName, cacheDirectory }) {
   if (cacheDirectory) {
     return path.join(cacheDirectory, pidFileName);
@@ -44,22 +88,41 @@ export async function setupPidFile({
     return null;
   }
 
-  const cleanup = () => {
-    try {
-      fsSync.unlinkSync(pidPath);
-    } catch {}
-  };
-
-  process.on('exit', cleanup);
+  registerPidFileCleanup(pidPath);
   return pidPath;
 }
 
 export function registerSignalHandlers(handler) {
-  process.on('SIGINT', () => handler('SIGINT'));
-  process.on('SIGTERM', () => handler('SIGTERM'));
+  if (typeof handler !== 'function') {
+    return () => {};
+  }
+
+  if (registeredSignalHandlers) {
+    process.off('SIGINT', registeredSignalHandlers.onSigint);
+    process.off('SIGTERM', registeredSignalHandlers.onSigterm);
+    registeredSignalHandlers = null;
+  }
+
+  const onSigint = () => handler('SIGINT');
+  const onSigterm = () => handler('SIGTERM');
+  process.on('SIGINT', onSigint);
+  process.on('SIGTERM', onSigterm);
+
+  registeredSignalHandlers = { onSigint, onSigterm };
+
+  return () => {
+    if (registeredSignalHandlers?.onSigint === onSigint) {
+      process.off('SIGINT', onSigint);
+      process.off('SIGTERM', onSigterm);
+      registeredSignalHandlers = null;
+    }
+  };
 }
 
 function isProcessRunning(pid) {
+  if (!Number.isInteger(pid) || pid <= 0) {
+    return false;
+  }
   try {
     process.kill(pid, 0);
     return true;
@@ -71,7 +134,8 @@ function isProcessRunning(pid) {
   }
 }
 
-export async function acquireWorkspaceLock({ cacheDirectory, workspaceDir = null } = {}) {
+export async function acquireWorkspaceLock({ cacheDirectory, workspaceDir = null, _retryCount = 0 } = {}) {
+  const MAX_LOCK_RETRIES = 3;
   if (!cacheDirectory || isTestEnv()) {
     return { acquired: true, lockPath: null };
   }
@@ -137,24 +201,21 @@ export async function acquireWorkspaceLock({ cacheDirectory, workspaceDir = null
       } else {
         await fs.unlink(lockPath).catch(() => {});
       }
-      return acquireWorkspaceLock({ cacheDirectory, workspaceDir });
+      if (_retryCount >= MAX_LOCK_RETRIES) {
+        console.warn(`[Server] Lock acquisition failed after ${MAX_LOCK_RETRIES} retries; starting in secondary mode.`);
+        return { acquired: false, lockPath, ownerPid: null };
+      }
+      const retryDelayMs = Math.min(
+        LOCK_RETRY_MAX_DELAY_MS,
+        LOCK_RETRY_BASE_DELAY_MS * 2 ** _retryCount
+      );
+      await delay(retryDelayMs);
+      return acquireWorkspaceLock({ cacheDirectory, workspaceDir, _retryCount: _retryCount + 1 });
     }
     throw err;
   }
 
-  const cleanup = () => {
-    try {
-      const raw = fsSync.readFileSync(lockPath, 'utf-8');
-      const current = JSON.parse(raw);
-      if (current && current.pid === process.pid) {
-        fsSync.unlinkSync(lockPath);
-      }
-    } catch {}
-  };
-
-  process.on('exit', cleanup);
-  process.on('SIGINT', cleanup);
-  process.on('SIGTERM', cleanup);
+  registerWorkspaceLockCleanup(lockPath);
 
   return { acquired: true, lockPath };
 }
@@ -169,6 +230,7 @@ export async function releaseWorkspaceLock({ cacheDirectory } = {}) {
     const current = JSON.parse(raw);
     if (current && current.pid === process.pid) {
       await fs.unlink(lockPath).catch(() => {});
+      workspaceLocksToCleanup.delete(lockPath);
     }
   } catch {}
 }

package/lib/utils.js

@@ -241,10 +241,11 @@ export function smartChunk(content, file, config) {
       if (currentChunk.length > 0) {
         const chunkText = currentChunk.join('\n');
         if (chunkText.trim().length > MIN_CHUNK_TEXT_LENGTH) {
+          const endLine = chunkStartLine + currentChunk.length;
           chunks.push({
             text: chunkText,
             startLine: chunkStartLine + 1,
-            endLine: i,
+            endLine,
             tokenCount: currentTokenCount + SPECIAL_TOKENS,
           });
         }
@@ -295,10 +296,11 @@ export function smartChunk(content, file, config) {
     if (shouldSplit && safeToSplit && currentChunk.length > 0) {
       const chunkText = currentChunk.join('\n');
       if (chunkText.trim().length > MIN_CHUNK_TEXT_LENGTH) {
+        const endLine = chunkStartLine + currentChunk.length;
         chunks.push({
           text: chunkText,
           startLine: chunkStartLine + 1,
-          endLine: i,
+          endLine,
           tokenCount: currentTokenCount,
         });
       }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@softerist/heuristic-mcp",
-  "version": "3.2.4",
+  "version": "3.2.6",
   "description": "An enhanced MCP server providing intelligent semantic code search with find-similar-code, recency ranking, and improved chunking. Fork of smart-coding-mcp.",
   "type": "module",
   "main": "index.js",