@softerist/heuristic-mcp 3.0.17 → 3.1.0

package/lib/config.js

@@ -1,16 +1,19 @@
-import fs from 'fs/promises';
-import path from 'path';
-import os from 'os';
-import crypto from 'crypto';
-import { fileURLToPath } from 'url';
-import { ProjectDetector } from './project-detector.js';
-import { parseJsonc } from './settings-editor.js';
+import fs from 'fs/promises';
+import path from 'path';
+import os from 'os';
+import { fileURLToPath } from 'url';
+import { ProjectDetector } from './project-detector.js';
+import { parseJsonc } from './settings-editor.js';
+import {
+  getLegacyWorkspaceCachePath,
+  getWorkspaceCachePath,
+} from './workspace-cache-key.js';
 import {
   EMBEDDING_PROCESS_DEFAULT_GC_MAX_REQUESTS_WITHOUT_COLLECTION,
   EMBEDDING_PROCESS_DEFAULT_GC_MIN_INTERVAL_MS,
   EMBEDDING_PROCESS_DEFAULT_GC_RSS_THRESHOLD_MB,
 } from './constants.js';
-import { getWorkspaceEnvKeys } from './workspace-env.js';
+import { getWorkspaceEnvDiagnosticKeys, getWorkspaceEnvKeys } from './workspace-env.js';
 
 const DEFAULT_MEMORY_CLEANUP_CONFIG = {
   enableExplicitGc: true, // Require --expose-gc for more aggressive memory cleanup
@@ -36,6 +39,7 @@ const DEFAULT_INDEXING_CONFIG = {
   prefilterContentMaxBytes: 512 * 1024, // 512KB - cache content during prefilter to avoid double reads
   maxResults: 5, // Maximum number of semantic search results to return
   watchFiles: true, // Enable file system watcher to re-index changed files in real-time
+  indexCheckpointIntervalMs: 5000, // Periodic cache checkpoint during full indexing (0 disables)
 };
 
 const DEFAULT_LOGGING_CONFIG = {
@@ -43,10 +47,11 @@ const DEFAULT_LOGGING_CONFIG = {
   memoryLogIntervalMs: 5000, // Verbose memory log cadence during indexing (ms)
 };
 
-const DEFAULT_CACHE_CONFIG = {
-  enableCache: true, // Whether to persist and reload embeddings between sessions
-  saveReaderWaitTimeoutMs: 5000, // Max wait for active reads before saving binary cache
-  cacheVectorAssumeFinite: true, // Assume vectors are finite (skip validation)
+const DEFAULT_CACHE_CONFIG = {
+  enableCache: true, // Whether to persist and reload embeddings between sessions
+  allowSystemWorkspaceCache: false, // Safety: block cache writes for IDE/system install directories unless explicitly overridden
+  saveReaderWaitTimeoutMs: 5000, // Max wait for active reads before saving binary cache
+  cacheVectorAssumeFinite: true, // Assume vectors are finite (skip validation)
   cacheVectorFloatDigits: null, // Decimal precision for cached vectors (null = default)
   cacheWriteHighWaterMark: 262144, // Write stream highWaterMark for cache files
   cacheVectorFlushChars: 262144, // Flush threshold (chars) for JSON writer
@@ -56,13 +61,14 @@ const DEFAULT_CACHE_CONFIG = {
   cacheVectorJoinChunkSize: 2048, // Chunk size for JSON join optimization
 };
 
-const DEFAULT_WORKER_CONFIG = {
-  workerThreads: 'auto', // 0 = run in main thread (no workers), "auto" = CPU cores - 1, or set a number
-  workerBatchTimeoutMs: 120000, // Timeout per worker batch before fallback (ms)
-  workerFailureThreshold: 1, // Open circuit after N worker failures
-  workerFailureCooldownMs: 10 * 60 * 1000, // Cooldown before retrying workers
-  workerMaxChunksPerBatch: 100, // Cap chunks per worker batch to reduce hang risk
-  allowSingleThreadFallback: false, // Allow fallback to main-thread embeddings if workers fail
+const DEFAULT_WORKER_CONFIG = {
+  workerThreads: 'auto', // 0 = run in main thread (no workers), "auto" = CPU cores - 1, or set a number
+  workerDisableHeavyModelOnWindows: true, // Safety guard: disable worker-pool mode for heavy models on Windows unless explicitly opted in
+  workerBatchTimeoutMs: 120000, // Timeout per worker batch before fallback (ms)
+  workerFailureThreshold: 1, // Open circuit after N worker failures
+  workerFailureCooldownMs: 10 * 60 * 1000, // Cooldown before retrying workers
+  workerMaxChunksPerBatch: 100, // Cap chunks per worker batch to reduce hang risk
+  allowSingleThreadFallback: false, // Allow fallback to main-thread embeddings if workers fail
   failFastEmbeddingErrors: false, // Abort worker embedding batch after repeated consecutive embed failures
 };
 
@@ -126,9 +132,11 @@ const SEARCH_KEYS = Object.freeze(Object.keys(DEFAULT_SEARCH_CONFIG));
 const CALL_GRAPH_KEYS = Object.freeze(Object.keys(DEFAULT_CALL_GRAPH_CONFIG));
 const ANN_KEYS = Object.freeze(Object.keys(DEFAULT_ANN_CONFIG));
 
-const DEFAULT_CONFIG = {
-  searchDirectory: '.',
-  fileExtensions: [
+const DEFAULT_CONFIG = {
+  searchDirectory: '.',
+  autoStopOtherServersOnStartup: true, // Ensure newly started workspace server can replace stale older heuristic-mcp instances
+  requireTrustedWorkspaceSignalForTools: false, // Fail workspace-bound tools when no current roots/env workspace signal is available
+  fileExtensions: [
     // JavaScript/TypeScript
     'js',
     'ts',
@@ -383,14 +391,16 @@ const DEFAULT_CONFIG = {
     removeDuplicates: true, // Remove duplicate workspace caches
   },
   watchFiles: DEFAULT_INDEXING_CONFIG.watchFiles,
+  indexCheckpointIntervalMs: DEFAULT_INDEXING_CONFIG.indexCheckpointIntervalMs,
   verbose: DEFAULT_LOGGING_CONFIG.verbose,
   memoryLogIntervalMs: DEFAULT_LOGGING_CONFIG.memoryLogIntervalMs,
   saveReaderWaitTimeoutMs: DEFAULT_CACHE_CONFIG.saveReaderWaitTimeoutMs,
-  workerThreads: DEFAULT_WORKER_CONFIG.workerThreads,
-  workerBatchTimeoutMs: DEFAULT_WORKER_CONFIG.workerBatchTimeoutMs,
-  workerFailureThreshold: DEFAULT_WORKER_CONFIG.workerFailureThreshold,
-  workerFailureCooldownMs: DEFAULT_WORKER_CONFIG.workerFailureCooldownMs,
-  workerMaxChunksPerBatch: DEFAULT_WORKER_CONFIG.workerMaxChunksPerBatch,
+  workerThreads: DEFAULT_WORKER_CONFIG.workerThreads,
+  workerDisableHeavyModelOnWindows: DEFAULT_WORKER_CONFIG.workerDisableHeavyModelOnWindows,
+  workerBatchTimeoutMs: DEFAULT_WORKER_CONFIG.workerBatchTimeoutMs,
+  workerFailureThreshold: DEFAULT_WORKER_CONFIG.workerFailureThreshold,
+  workerFailureCooldownMs: DEFAULT_WORKER_CONFIG.workerFailureCooldownMs,
+  workerMaxChunksPerBatch: DEFAULT_WORKER_CONFIG.workerMaxChunksPerBatch,
   allowSingleThreadFallback: DEFAULT_WORKER_CONFIG.allowSingleThreadFallback,
   failFastEmbeddingErrors: DEFAULT_WORKER_CONFIG.failFastEmbeddingErrors,
   embeddingProcessPerBatch: DEFAULT_EMBEDDING_CONFIG.embeddingProcessPerBatch,
@@ -630,6 +640,32 @@ async function resolveWorkspaceCandidate(rawValue) {
   return candidate;
 }
 
+function formatWorkspaceProbeValue(rawValue, maxLength = 120) {
+  const value = String(rawValue || '').trim();
+  if (!value) return '';
+  if (value.length <= maxLength) return value;
+  return `${value.slice(0, maxLength - 3)}...`;
+}
+
+function logWorkspaceEnvProbe(entries) {
+  if (!entries || entries.length === 0) {
+    console.info('[Config] Workspace env probe: no workspace-like environment variables were set.');
+    return;
+  }
+
+  const preview = entries.slice(0, 10).map((entry) => {
+    const scope = entry.priority ? 'priority' : 'diagnostic';
+    const status = entry.ignoredNonProject
+      ? `ignored-non-project:${entry.resolvedPath}`
+      : entry.resolvedPath
+        ? `valid:${entry.resolvedPath}`
+        : `invalid:${entry.value}`;
+    return `${entry.key}[${scope}]=${status}`;
+  });
+  const suffix = entries.length > 10 ? ` (+${entries.length - 10} more)` : '';
+  console.info(`[Config] Workspace env probe: ${preview.join('; ')}${suffix}`);
+}
+
 function logWorkspaceResolution(resolution) {
   if (!resolution || !resolution.path) return;
 
@@ -659,6 +695,24 @@ function logWorkspaceResolution(resolution) {
   console.info(`[Config] Workspace resolution: process.cwd() -> ${resolution.path}`);
 }
 
+/**
+ * Heuristic check: is this path likely an IDE install or system directory
+ * rather than a user workspace? Used to warn when workspace resolution
+ * falls back to process.cwd() and lands in a non-project location.
+ */
+export function isNonProjectDirectory(dir) {
+  const normalized = dir.replace(/\\/g, '/').toLowerCase();
+  const markers = [
+    '/program files/',
+    '/program files (x86)/',
+    '/appdata/local/programs/',
+    '/appdata/roaming/',
+    '/applications/',
+    '/contents/resources/',
+  ];
+  return markers.some((m) => normalized.includes(m));
+}
+
 async function resolveWorkspaceDir(workspaceDir) {
   if (workspaceDir) {
     return {
@@ -673,42 +727,90 @@ async function resolveWorkspaceDir(workspaceDir) {
     };
   }
 
-  for (const key of getWorkspaceEnvKeys()) {
-    const candidate = await resolveWorkspaceCandidate(process.env[key]);
-    if (candidate) {
-      return {
-        path: candidate,
-        source: 'env',
-        envKey: key,
+  const prioritizedEnvKeys = getWorkspaceEnvKeys();
+  const prioritizedEnvKeySet = new Set(prioritizedEnvKeys);
+  const workspaceEnvProbe = [];
+
+  for (const key of prioritizedEnvKeys) {
+    const rawValue = process.env[key];
+    if (rawValue === undefined || rawValue === null || String(rawValue).trim() === '') {
+      continue;
+    }
+    const value = formatWorkspaceProbeValue(rawValue);
+    const candidate = await resolveWorkspaceCandidate(rawValue);
+    workspaceEnvProbe.push({
+      key,
+      value,
+      resolvedPath: candidate,
+      priority: true,
+      ignoredNonProject: Boolean(candidate && isNonProjectDirectory(candidate)),
+    });
+    if (candidate && !isNonProjectDirectory(candidate)) {
+      return {
+        path: candidate,
+        source: 'env',
+        envKey: key,
+        workspaceEnvProbe,
       };
     }
   }
 
+  for (const key of getWorkspaceEnvDiagnosticKeys()) {
+    if (prioritizedEnvKeySet.has(key)) continue;
+    const rawValue = process.env[key];
+    if (rawValue === undefined || rawValue === null || String(rawValue).trim() === '') {
+      continue;
+    }
+    const value = formatWorkspaceProbeValue(rawValue);
+    const candidate = await resolveWorkspaceCandidate(rawValue);
+    workspaceEnvProbe.push({
+      key,
+      value,
+      resolvedPath: candidate,
+      priority: false,
+    });
+  }
+
+  logWorkspaceEnvProbe(workspaceEnvProbe);
+
   const cwd = path.resolve(process.cwd());
+
+  // Note: if CWD is an IDE/system dir, MCP roots detection in index.js will auto-correct.
+  if (isNonProjectDirectory(cwd)) {
+    console.info(
+      `[Config] CWD "${cwd}" appears to be an IDE/system directory. MCP roots detection will attempt auto-correction.`
+    );
+  }
+
   const root = await findWorkspaceRoot(cwd);
   if (root !== cwd) {
     return {
       path: root,
       source: 'cwd-root-search',
       fromPath: cwd,
+      workspaceEnvProbe,
     };
   }
   return {
     path: cwd,
     source: 'cwd',
+    workspaceEnvProbe,
   };
 }
 
 export async function loadConfig(workspaceDir = null) {
+  let workspaceResolution = null;
+  let baseDir = null;
+  let searchDirectoryFromConfig = false;
+
   try {
     // Determine the base directory for configuration
-    let baseDir;
     let configPath;
 
     let serverDir = null;
     if (workspaceDir) {
       // Workspace mode: load config from workspace root
-      const workspaceResolution = await resolveWorkspaceDir(workspaceDir);
+      workspaceResolution = await resolveWorkspaceDir(workspaceDir);
       baseDir = workspaceResolution.path;
       console.info(`[Config] Workspace mode: ${baseDir}`);
       logWorkspaceResolution(workspaceResolution);
@@ -717,7 +819,7 @@ export async function loadConfig(workspaceDir = null) {
       // but use process.cwd() as base for searching if not specified otherwise
       const scriptDir = path.dirname(fileURLToPath(import.meta.url));
       serverDir = path.resolve(scriptDir, '..');
-      const workspaceResolution = await resolveWorkspaceDir(null);
+      workspaceResolution = await resolveWorkspaceDir(null);
       baseDir = workspaceResolution.path;
       logWorkspaceResolution(workspaceResolution);
     }
@@ -772,6 +874,7 @@ export async function loadConfig(workspaceDir = null) {
 
     // Set search directory (respect user override when provided)
     if (userConfig.searchDirectory) {
+      searchDirectoryFromConfig = true;
       config.searchDirectory = path.isAbsolute(userConfig.searchDirectory)
         ? userConfig.searchDirectory
         : path.join(baseDir, userConfig.searchDirectory);
@@ -779,25 +882,35 @@ export async function loadConfig(workspaceDir = null) {
       config.searchDirectory = baseDir;
     }
 
-    // Determine cache directory
-    if (userConfig.cacheDirectory) {
-      // User explicitly set a cache path in their config file
-      config.cacheDirectory = path.isAbsolute(userConfig.cacheDirectory)
-        ? userConfig.cacheDirectory
-        : path.join(baseDir, userConfig.cacheDirectory);
-    } else {
-      // Use global cache directory to prevent cluttering project root
-      // Hash the absolute path to ensure uniqueness per project
-      const projectHash = crypto
-        .createHash('md5')
-        .update(config.searchDirectory)
-        .digest('hex')
-        .slice(0, 12);
-      const globalCacheRoot = getGlobalCacheDir();
-      config.cacheDirectory = path.join(globalCacheRoot, 'heuristic-mcp', projectHash);
-
-      // Support legacy .smart-coding-cache if it already exists in the project root
-      const legacyPath = path.join(baseDir, '.smart-coding-cache');
+    // Determine cache directory
+    if (userConfig.cacheDirectory) {
+      // User explicitly set a cache path in their config file
+      config.cacheDirectory = path.isAbsolute(userConfig.cacheDirectory)
+        ? userConfig.cacheDirectory
+        : path.join(baseDir, userConfig.cacheDirectory);
+    } else {
+      // Use global cache directory to prevent cluttering project root.
+      // Workspace path is normalized for hashing so Windows drive-letter case
+      // differences (e.g. F:\ vs f:\) resolve to the same cache id.
+      const globalCacheRoot = getGlobalCacheDir();
+      const normalizedCachePath = getWorkspaceCachePath(config.searchDirectory, globalCacheRoot);
+      const legacyCachePath = getLegacyWorkspaceCachePath(config.searchDirectory, globalCacheRoot);
+
+      if (
+        normalizedCachePath !== legacyCachePath &&
+        !(await pathExists(normalizedCachePath)) &&
+        (await pathExists(legacyCachePath))
+      ) {
+        config.cacheDirectory = legacyCachePath;
+        console.info(
+          `[Config] Using legacy cache path for compatibility: ${path.basename(legacyCachePath)}`
+        );
+      } else {
+        config.cacheDirectory = normalizedCachePath;
+      }
+
+      // Support legacy .smart-coding-cache if it already exists in the project root
+      const legacyPath = path.join(baseDir, '.smart-coding-cache');
       try {
         const stats = await fs.stat(legacyPath);
         if (stats.isDirectory()) {
@@ -840,6 +953,16 @@ export async function loadConfig(workspaceDir = null) {
     console.warn(`[Config] Error: ${error.message}`);
   }
 
+  config.workspaceResolution = {
+    source: workspaceResolution?.source || 'unknown',
+    envKey: workspaceResolution?.envKey || null,
+    fromPath: workspaceResolution?.fromPath || null,
+    baseDirectory: baseDir,
+    searchDirectory: config.searchDirectory,
+    searchDirectoryFromConfig,
+    workspaceEnvProbe: workspaceResolution?.workspaceEnvProbe || [],
+  };
+
   // Apply environment variable overrides (prefix: SMART_CODING_) with validation
   if (process.env.SMART_CODING_VERBOSE !== undefined) {
     const value = process.env.SMART_CODING_VERBOSE;
@@ -932,10 +1055,43 @@ export async function loadConfig(workspaceDir = null) {
     }
   }
 
-  if (process.env.SMART_CODING_WATCH_FILES !== undefined) {
-    const value = process.env.SMART_CODING_WATCH_FILES;
-    if (value === 'true' || value === 'false') {
-      config.watchFiles = value === 'true';
+  if (process.env.SMART_CODING_WATCH_FILES !== undefined) {
+    const value = process.env.SMART_CODING_WATCH_FILES;
+    if (value === 'true' || value === 'false') {
+      config.watchFiles = value === 'true';
+    }
+  }
+
+  if (process.env.SMART_CODING_REQUIRE_TRUSTED_WORKSPACE_SIGNAL_FOR_TOOLS !== undefined) {
+    const value = process.env.SMART_CODING_REQUIRE_TRUSTED_WORKSPACE_SIGNAL_FOR_TOOLS;
+    if (value === 'true' || value === 'false') {
+      config.requireTrustedWorkspaceSignalForTools = value === 'true';
+    } else {
+      console.warn(
+        `[Config] Invalid SMART_CODING_REQUIRE_TRUSTED_WORKSPACE_SIGNAL_FOR_TOOLS: ${value}, using default`
+      );
+    }
+  }
+
+  if (process.env.SMART_CODING_AUTO_STOP_OTHER_SERVERS_ON_STARTUP !== undefined) {
+    const value = process.env.SMART_CODING_AUTO_STOP_OTHER_SERVERS_ON_STARTUP;
+    if (value === 'true' || value === 'false') {
+      config.autoStopOtherServersOnStartup = value === 'true';
+    } else {
+      console.warn(
+        `[Config] Invalid SMART_CODING_AUTO_STOP_OTHER_SERVERS_ON_STARTUP: ${value}, using default`
+      );
+    }
+  }
+
+  if (process.env.SMART_CODING_INDEX_CHECKPOINT_INTERVAL_MS !== undefined) {
+    const value = parseInt(process.env.SMART_CODING_INDEX_CHECKPOINT_INTERVAL_MS, 10);
+    if (!isNaN(value) && value >= 0) {
+      config.indexCheckpointIntervalMs = value;
+    } else {
+      console.warn(
+        `[Config] Invalid SMART_CODING_INDEX_CHECKPOINT_INTERVAL_MS: ${process.env.SMART_CODING_INDEX_CHECKPOINT_INTERVAL_MS}, using default`
+      );
     }
   }
 
@@ -1138,7 +1294,7 @@ export async function loadConfig(workspaceDir = null) {
     }
   }
 
-  if (process.env.SMART_CODING_WORKER_THREADS !== undefined) {
+  if (process.env.SMART_CODING_WORKER_THREADS !== undefined) {
     const value = process.env.SMART_CODING_WORKER_THREADS.trim().toLowerCase();
     if (value === 'auto') {
       config.workerThreads = 'auto';
@@ -1152,7 +1308,21 @@ export async function loadConfig(workspaceDir = null) {
         );
       }
     }
-  }
+  }
+
+  const workerDisableHeavyModelOnWindowsEnv =
+    process.env.SMART_CODING_WORKER_DISABLE_HEAVY_MODEL_ON_WINDOWS ??
+    process.env.SMART_CODING_WORKER_DISABLE_HEAVY_MODEL_WINDOWS;
+  if (workerDisableHeavyModelOnWindowsEnv !== undefined) {
+    const value = workerDisableHeavyModelOnWindowsEnv;
+    if (value === 'true' || value === 'false') {
+      config.workerDisableHeavyModelOnWindows = value === 'true';
+    } else {
+      console.warn(
+        `[Config] Invalid SMART_CODING_WORKER_DISABLE_HEAVY_MODEL_ON_WINDOWS: ${value}, using default`
+      );
+    }
+  }
 
   if (process.env.SMART_CODING_EMBEDDING_FAIL_FAST_BREAKER !== undefined) {
     const value = process.env.SMART_CODING_EMBEDDING_FAIL_FAST_BREAKER;

package/lib/constants.js

@@ -25,15 +25,35 @@ export const WORKSPACE_ENV_VARS = Object.freeze([
 ]);
 
 /**
- * Prefix for dynamic workspace-related env vars (provider-specific).
+ * Prefixes for dynamic workspace-related env vars (provider-specific).
+ */
+export const DYNAMIC_WORKSPACE_ENV_PREFIXES = Object.freeze([
+  'CODEX_',
+  'ANTIGRAVITY_',
+  'CURSOR_',
+  'CLAUDE_',
+  'WINDSURF_',
+  'WARP_',
+  'MCP_',
+  'VSCODE_',
+]);
+
+/**
+ * Backward-compatible alias for legacy single-prefix consumers.
  */
-export const DYNAMIC_WORKSPACE_ENV_PREFIX = 'CODEX_';
+export const DYNAMIC_WORKSPACE_ENV_PREFIX = DYNAMIC_WORKSPACE_ENV_PREFIXES[0];
 
 /**
  * Pattern used when ranking provider-specific workspace env vars.
  */
 export const WORKSPACE_ENV_KEY_PATTERN = /(WORKSPACE|PROJECT|ROOT|CWD|DIR)/i;
 
+/**
+ * Broad token used to discover unknown provider keys safely.
+ * We only auto-discover generic env keys containing "WORKSPACE".
+ */
+export const WORKSPACE_ENV_GENERIC_DISCOVERY_PATTERN = /WORKSPACE/i;
+
 // ================================
 // Chunking Constants
 // ================================

package/lib/embed-query-process.js

@@ -6,7 +6,7 @@ import readline from 'readline';
 const __dirname = path.dirname(fileURLToPath(import.meta.url));
 const EMBEDDING_PROCESS_PATH = path.join(__dirname, 'embedding-process.js');
 
-// Persistent child process pool - single instance
+
 let persistentChild = null;
 let childReadline = null;
 let idleTimer = null;
@@ -14,16 +14,13 @@ let currentConfig = null;
 let pendingRequests = [];
 let isProcessingRequest = false;
 
-// Default idle timeout: 30 seconds - child exits after this to free memory
+
 const DEFAULT_IDLE_TIMEOUT_MS = 30000;
 
-/**
- * Get or create the persistent embedding child process.
- * The child stays alive for consecutive queries, then exits after idle timeout.
- */
+
 function getOrCreateChild(config) {
   if (persistentChild && !persistentChild.killed) {
-    // Reset idle timer on each use
+    
     resetIdleTimer(config);
     return persistentChild;
   }
@@ -41,7 +38,7 @@ function getOrCreateChild(config) {
 
   currentConfig = config;
 
-  // Set up readline for line-by-line response parsing
+  
   childReadline = readline.createInterface({
     input: persistentChild.stdout,
     crlfDelay: Infinity,
@@ -50,7 +47,7 @@ function getOrCreateChild(config) {
   childReadline.on('line', (line) => {
     if (!line.trim()) return;
     
-    // Process the response for the current pending request
+    
     if (pendingRequests.length > 0) {
       const { resolve, reject, startTime } = pendingRequests.shift();
       try {
@@ -93,7 +90,7 @@ function getOrCreateChild(config) {
   persistentChild.on('error', (err) => {
     console.error(`[EmbedPool] Child process error: ${err.message}`);
     cleanupChild();
-    // Reject all pending requests
+    
     for (const { reject } of pendingRequests) {
       reject(new Error(`Child process error: ${err.message}`));
     }
@@ -105,7 +102,7 @@ function getOrCreateChild(config) {
       console.info(`[EmbedPool] Child process exited with code ${code}`);
     }
     cleanupChild();
-    // Reject remaining pending requests so they can retry
+    
     for (const { reject } of pendingRequests) {
       reject(new Error(`Child process exited unexpectedly with code ${code}`));
     }
@@ -154,10 +151,10 @@ function cleanupChild() {
 function shutdownChild() {
   if (persistentChild && !persistentChild.killed) {
     try {
-      // Send shutdown command
+      
       persistentChild.stdin.write(JSON.stringify({ type: 'shutdown' }) + '\n');
     } catch {
-      // If write fails, force kill
+      
       persistentChild.kill();
     }
   }
@@ -183,15 +180,7 @@ function processNextRequest() {
   }
 }
 
-/**
- * Embed a single query string using a persistent child process.
- * The child process stays alive for consecutive queries, then exits after idle timeout.
- * This gives fast consecutive searches + memory cleanup after idle period.
- * 
- * @param {string} query - The query text to embed
- * @param {object} config - Configuration object with embeddingModel and embeddingProcessNumThreads
- * @returns {Promise<Float32Array>} - The embedding vector
- */
+
 export async function embedQueryInChildProcess(query, config) {
   return new Promise((resolve, reject) => {
     const payload = {
@@ -212,17 +201,12 @@ export async function embedQueryInChildProcess(query, config) {
   });
 }
 
-/**
- * Force shutdown the persistent child process to immediately free memory.
- * Called when user explicitly wants to free memory.
- */
+
 export function forceShutdownEmbeddingPool() {
   shutdownChild();
 }
 
-/**
- * Check if the persistent child process is currently running.
- */
+
 export function isEmbeddingPoolActive() {
   return persistentChild !== null && !persistentChild.killed;
 }