@softerist/heuristic-mcp 3.2.0 → 3.2.2

package/config.jsonc

@@ -628,7 +628,7 @@
     "**/.smart-coding-cache/**",
   ],
   // Indexing controls.
-  "indexing": {
+  "indexing": {
     // Enable project-type detection + smart ignore patterns.
     "smartIndexing": true,
     // Lines per chunk.
@@ -645,18 +645,10 @@
     "watchFiles": true,
     // Save incremental index checkpoints every 2s so interrupted runs can resume with minimal rework.
     // Increase to 5000-10000 on slower disks if checkpoint writes feel too frequent.
-    "indexCheckpointIntervalMs": 2000,
-  },
-  // Server lifecycle controls.
-  // When true, a newly started server instance will terminate older heuristic-mcp server processes.
-  // This helps prevent stale workspace binding after IDE reloads/window switches.
-  "autoStopOtherServersOnStartup": true,
-  // Safety guard for IDE sessions:
-  // when true, semantic/index tools require a current trusted workspace signal
-  // (MCP roots or explicit workspace env), otherwise the call fails fast.
-  "requireTrustedWorkspaceSignalForTools": true,
-  // Logging and diagnostics.
-  "logging": {
+    "indexCheckpointIntervalMs": 2000,
+  },
+  // Logging and diagnostics.
+  "logging": {
     // Enable verbose logging.
     "verbose": true,
   },
@@ -694,10 +686,7 @@
   "worker": {
     // Number of embedding workers (0 disables).
     // Windows + heavy Jina models are more stable with child-process embedding than worker pools.
-    "workerThreads": 1,
-    // Safety guard for heavy models on Windows.
-    // Keep true (recommended). Set false only to opt in to experimental heavy-model workers on Windows.
-    "workerDisableHeavyModelOnWindows": false,
+    "workerThreads": 0,
     // Worker batch timeout in milliseconds.
     "workerBatchTimeoutMs": 120000,
     // Failures before worker circuit opens.

package/features/ann-config.js

@@ -25,17 +25,28 @@ export class AnnConfigTool {
       return this.cache.setEfSearch(efSearch);
     }
 
-    if (action === 'rebuild') {
-      
-      this.cache.invalidateAnnIndex();
-      const index = await this.cache.ensureAnnIndex();
-      return {
-        success: index !== null,
-        message: index
-          ? 'ANN index rebuilt successfully'
-          : 'ANN index rebuild failed or not available',
-      };
-    }
+    if (action === 'rebuild') {
+      try {
+        
+        this.cache.invalidateAnnIndex();
+        const index = await this.cache.ensureAnnIndex();
+        if (!index) {
+          return {
+            success: false,
+            error: 'ANN index rebuild failed or not available',
+          };
+        }
+        return {
+          success: true,
+          message: 'ANN index rebuilt successfully',
+        };
+      } catch (error) {
+        return {
+          success: false,
+          error: error instanceof Error ? error.message : String(error),
+        };
+      }
+    }
 
     return {
       success: false,
@@ -43,10 +54,10 @@ export class AnnConfigTool {
     };
   }
 
-  formatResults(result) {
-    if (result.success === false) {
-      return `Error: ${result.error}`;
-    }
+  formatResults(result) {
+    if (result.success === false) {
+      return `Error: ${result.error || result.message || 'Unknown error'}`;
+    }
 
     if (result.enabled !== undefined) {
       

package/features/index-codebase.js

@@ -2857,16 +2857,16 @@ export class CodebaseIndexer {
 
       const totalDurationMs = Date.now() - totalStartTime;
       const totalTime = (totalDurationMs / 1000).toFixed(1);
-      console.info(
-        `[Indexer] Embedding pass complete: ${totalChunks} chunks from ${filesToProcess.length} files in ${totalTime}s`
-      );
-
-      
-      this.sendProgress(
-        100,
-        100,
-        `Complete: ${totalChunks} chunks from ${filesToProcess.length} files in ${totalTime}s`
-      );
+      console.info(
+        `[Indexer] Embedding pass complete: ${totalChunks} chunks from ${filesToProcess.length} files in ${totalTime}s`
+      );
+
+      
+      this.sendProgress(
+        95,
+        100,
+        `Embedding complete; saving cache (${totalChunks} chunks from ${filesToProcess.length} files)...`
+      );
 
       this.cache.setLastIndexDuration?.(totalDurationMs);
       this.cache.setLastIndexStats?.({
@@ -2881,7 +2881,13 @@ export class CodebaseIndexer {
         lastCheckpointIntervalMs: checkpointIntervalMs,
         lastCheckpointSaves: checkpointSaveCount,
       });
-      await this.cache.save();
+      await this.cache.save({ throwOnError: true });
+
+      this.sendProgress(
+        100,
+        100,
+        `Complete: ${totalChunks} chunks from ${filesToProcess.length} files in ${totalTime}s`
+      );
 
       const vectorStoreSnapshot = this.cache.getVectorStore();
       const totalFiles = new Set(vectorStoreSnapshot.map((v) => v.file)).size;

package/features/lifecycle.js

@@ -14,8 +14,23 @@ import {
   upsertMcpServerEntryInText,
 } from '../lib/settings-editor.js';
 
-const execPromise = util.promisify(exec);
-const PID_FILE_NAME = '.heuristic-mcp.pid';
+const execPromise = util.promisify(exec);
+const PID_FILE_NAME = '.heuristic-mcp.pid';
+const BINARY_TELEMETRY_FILE = 'binary-store-telemetry.json';
+
+async function readBinaryTelemetry(cacheDir) {
+  const telemetryPath = path.join(cacheDir, BINARY_TELEMETRY_FILE);
+  try {
+    return JSON.parse(await fs.readFile(telemetryPath, 'utf-8'));
+  } catch {
+    return null;
+  }
+}
+
+function hasNonZeroBinaryTelemetry(totals) {
+  if (!totals || typeof totals !== 'object') return false;
+  return Object.values(totals).some((value) => Number.isFinite(value) && value > 0);
+}
 
 function getUserHomeDir() {
   if (process.platform === 'win32' && process.env.USERPROFILE) {
@@ -1208,18 +1223,18 @@ export async function status({ fix = false, cacheOnly = false, workspaceDir = nu
             if (progressData.indexMode) {
               console.info(`   Current index mode: ${String(progressData.indexMode)}`);
             }
-            if (
-              progressData.workerCircuitOpen &&
-              Number.isFinite(progressData.workersDisabledUntil)
-            ) {
+            if (
+              progressData.workerCircuitOpen &&
+              Number.isFinite(progressData.workersDisabledUntil)
+            ) {
               const remainingMs = progressData.workersDisabledUntil - Date.now();
               const remainingLabel = formatDurationMs(Math.max(0, remainingMs));
               console.info(`   Workers paused: ${remainingLabel || '0s'} remaining`);
               console.info(
                 `   Workers disabled until: ${formatDateTime(progressData.workersDisabledUntil)}`
-              );
-            }
-          } else {
+              );
+            }
+          } else {
             if (metaData) {
               console.info('   Summary: Cached snapshot available; no update running.');
             } else {
@@ -1227,6 +1242,35 @@ export async function status({ fix = false, cacheOnly = false, workspaceDir = nu
             }
           }
 
+          const binaryTelemetry = await readBinaryTelemetry(cacheDir);
+          if (binaryTelemetry?.totals && hasNonZeroBinaryTelemetry(binaryTelemetry.totals)) {
+            const totals = binaryTelemetry.totals;
+            console.info(
+              `   Binary telemetry: swaps=${totals.atomicReplaceAttempts || 0} ok=${totals.atomicReplaceSuccesses || 0} fail=${totals.atomicReplaceFailures || 0}`
+            );
+            console.info(
+              `   Binary telemetry: retries=${totals.renameRetryCount || 0} fallbackCopies=${totals.fallbackCopyCount || 0} rollbacks=${totals.rollbackCount || 0}`
+            );
+            if ((totals.rollbackRestoreFailureCount || 0) > 0) {
+              console.info(
+                `   Binary telemetry: rollback restore failures=${totals.rollbackRestoreFailureCount}`
+              );
+            }
+            if ((totals.startupCleanupRuns || 0) > 0 || (totals.staleTempFilesRemoved || 0) > 0) {
+              console.info(
+                `   Startup temp cleanup: runs=${totals.startupCleanupRuns || 0} removed=${totals.staleTempFilesRemoved || 0} skippedActive=${totals.staleTempFilesSkippedActive || 0}`
+              );
+            }
+            if (binaryTelemetry.lastAtomicReplace?.at) {
+              console.info(
+                `   Last atomic replace: ${formatDateTime(binaryTelemetry.lastAtomicReplace.at)}`
+              );
+            }
+            if (binaryTelemetry.lastError?.message) {
+              console.info(`   Last binary error: ${binaryTelemetry.lastError.message}`);
+            }
+          }
+
           if (metaData && isProgressIncomplete) {
             console.info('   Indexing state: Cached snapshot available; incremental update running.');
           } else if (metaData) {

package/features/register.js

@@ -265,22 +265,22 @@ function ideMatchesFilter(name, filter) {
 
 function getServerConfigForIde(name) {
   const normalizedName = normalizeIdeName(name);
+  const workspaceArgs = [
+    '--workspace',
+    '${workspaceFolder}',
+    '--workspace',
+    '${workspaceRoot}',
+    '--workspace',
+    '${workspace}',
+  ];
   const config = {
     command: 'heuristic-mcp',
-    args: [],
+    // Prefer explicit workspace forwarding when supported by the host.
+    // Unexpanded placeholders are safely ignored by CLI workspace parsing.
+    args: workspaceArgs,
   };
 
   if (normalizedName === 'antigravity') {
-    // Prefer explicit workspace forwarding in VS Code-compatible clients.
-    // If the variable is not expanded by the IDE, CLI parsing safely ignores it.
-    config.args = [
-      '--workspace',
-      '${workspaceFolder}',
-      '--workspace',
-      '${workspaceRoot}',
-      '--workspace',
-      '${workspace}',
-    ];
     // Allow provider-specific workspace env discovery as a backup signal.
     config.env = {
       HEURISTIC_MCP_ENABLE_DYNAMIC_WORKSPACE_ENV: 'true',

package/features/set-workspace.js

@@ -4,6 +4,7 @@ import path from 'path';
 import fs from 'fs/promises';
 import { acquireWorkspaceLock, releaseWorkspaceLock } from '../lib/server-lifecycle.js';
 import { getWorkspaceCachePath } from '../lib/workspace-cache-key.js';
+import { cleanupStaleBinaryArtifacts } from '../lib/vector-store-binary.js';
 
 
 function getWorkspaceCacheDir(workspacePath, globalCacheDir) {
@@ -185,13 +186,16 @@ export class SetWorkspaceFeature {
       await releaseWorkspaceLock({ cacheDirectory: previousCache });
     }
 
-    
-    if (this.cache && typeof this.cache.load === 'function') {
-      try {
-        await this.cache.load();
-      } catch (err) {
-        console.warn(`[SetWorkspace] Failed to load cache: ${err.message}`);
-      }
+    
+    if (this.cache && typeof this.cache.load === 'function') {
+      try {
+        if (this.config.vectorStoreFormat === 'binary') {
+          await cleanupStaleBinaryArtifacts(newCacheDir);
+        }
+        await this.cache.load();
+      } catch (err) {
+        console.warn(`[SetWorkspace] Failed to load cache: ${err.message}`);
+      }
     }
 
     

package/index.js

@@ -49,9 +49,10 @@ import {
   stopOtherHeuristicServers,
 } from './lib/server-lifecycle.js';
 
-import { EmbeddingsCache } from './lib/cache.js';
-import { CodebaseIndexer } from './features/index-codebase.js';
-import { HybridSearch } from './features/hybrid-search.js';
+import { EmbeddingsCache } from './lib/cache.js';
+import { cleanupStaleBinaryArtifacts } from './lib/vector-store-binary.js';
+import { CodebaseIndexer } from './features/index-codebase.js';
+import { HybridSearch } from './features/hybrid-search.js';
 
 import * as IndexCodebaseFeature from './features/index-codebase.js';
 import * as HybridSearchFeature from './features/hybrid-search.js';
@@ -827,12 +828,21 @@ async function initialize(workspaceDir) {
     }
   };
 
-  
-  
-
-  
-  cache = new EmbeddingsCache(config);
-  console.info(`[Server] Cache directory: ${config.cacheDirectory}`);
+  
+  
+
+  
+  if (config.vectorStoreFormat === 'binary') {
+    try {
+      await cleanupStaleBinaryArtifacts(config.cacheDirectory, { logger: console });
+    } catch (err) {
+      console.warn(`[Cache] Startup temp cleanup failed: ${err.message}`);
+    }
+  }
+
+  
+  cache = new EmbeddingsCache(config);
+  console.info(`[Server] Cache directory: ${config.cacheDirectory}`);
 
   
   indexer = new CodebaseIndexer(embedder, cache, config, server);
@@ -883,6 +893,9 @@ async function initialize(workspaceDir) {
       config.searchDirectory = candidate.workspace;
       config.cacheDirectory = candidate.cacheDirectory;
       await fs.mkdir(config.cacheDirectory, { recursive: true });
+      if (config.vectorStoreFormat === 'binary') {
+        await cleanupStaleBinaryArtifacts(config.cacheDirectory, { logger: console });
+      }
       await cache.load();
       console.info(
         `[Server] Auto-attached workspace cache (${reason}): ${candidate.workspace} via ${candidate.source}`
@@ -1162,19 +1175,34 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
   for (const feature of features) {
     const toolDef = feature.module.getToolDefinition(config);
 
-    if (request.params.name === toolDef.name) {
-      
-      
-      if (typeof feature.handler !== 'function') {
-        return {
+    if (request.params.name === toolDef.name) {
+      
+      
+      if (typeof feature.handler !== 'function') {
+        return {
           content: [{
             type: 'text',
             text: `Tool "${toolDef.name}" is not ready. Server may still be initializing.`,
           }],
-          isError: true,
-        };
+          isError: true,
+        };
+      }
+      let result;
+      try {
+        result = await feature.handler(request, feature.instance);
+      } catch (error) {
+        const message = error instanceof Error ? error.message : String(error);
+        console.error(`[Server] Tool ${toolDef.name} failed: ${message}`);
+        return {
+          content: [
+            {
+              type: 'text',
+              text: `Error: ${message || 'Unknown tool failure'}`,
+            },
+          ],
+          isError: true,
+        };
       }
-      const result = await feature.handler(request, feature.instance);
       if (toolDef.name === 'f_set_workspace' && !isToolResponseError(result)) {
         trustWorkspacePath(config.searchDirectory);
       }

package/lib/cache.js

@@ -266,10 +266,12 @@ export class EmbeddingsCache {
     };
 
     
-    this.saveQueue = Promise.resolve();
-    this._saveTimer = null;
-    this._saveRequested = false;
-    this._savePromise = null;
+    this.saveQueue = Promise.resolve();
+    this._saveTimer = null;
+    this._saveRequested = false;
+    this._savePromise = null;
+    this._saveThrowOnError = false;
+    this.lastSaveError = null;
 
     
     this.annIndex = null;
@@ -771,31 +773,39 @@ export class EmbeddingsCache {
 
   
 
-  save() {
-    if (!this.config.enableCache) return Promise.resolve();
-
-    this._saveRequested = true;
-
-    if (this._saveTimer) return this._savePromise ?? Promise.resolve();
+  save({ throwOnError = false } = {}) {
+    if (!this.config.enableCache) return Promise.resolve();
+
+    this._saveRequested = true;
+    if (throwOnError) {
+      this._saveThrowOnError = true;
+    }
+
+    if (this._saveTimer) return this._savePromise ?? Promise.resolve();
 
     const debounceMs = Number.isInteger(this.config.saveDebounceMs)
       ? this.config.saveDebounceMs
       : 250;
 
-    this._savePromise = new Promise((resolve, reject) => {
-      this._saveTimer = setTimeout(() => {
-        this._saveTimer = null;
-
-        this.saveQueue = this.saveQueue
-          .then(async () => {
-            while (this._saveRequested) {
-              this._saveRequested = false;
-              await this.performSave();
-            }
-          })
-          .then(resolve, reject)
-          .finally(() => {
-            this._savePromise = null;
+    this._savePromise = new Promise((resolve, reject) => {
+      this._saveTimer = setTimeout(() => {
+        this._saveTimer = null;
+        const rejectOnSaveError = this._saveThrowOnError;
+        this._saveThrowOnError = false;
+
+        this.saveQueue = this.saveQueue
+          .catch(() => {
+            
+          })
+          .then(async () => {
+            while (this._saveRequested) {
+              this._saveRequested = false;
+              await this.performSave({ throwOnError: rejectOnSaveError });
+            }
+          })
+          .then(resolve, reject)
+          .finally(() => {
+            this._savePromise = null;
           });
       }, debounceMs);
     });
@@ -803,7 +813,7 @@ export class EmbeddingsCache {
     return this._savePromise;
   }
 
-  async performSave() {
+  async performSave({ throwOnError = false } = {}) {
     
     this._saveInProgress = true;
     if (
@@ -988,9 +998,9 @@ export class EmbeddingsCache {
 
       
       
-      if (
-        this.config.annIndexCache !== false &&
-        this.annPersistDirty &&
+      if (
+        this.config.annIndexCache !== false &&
+        this.annPersistDirty &&
         !this.annDirty &&
         !this._annWriting &&
         this.annIndex &&
@@ -1009,10 +1019,12 @@ export class EmbeddingsCache {
           console.warn(`[ANN] Failed to persist ANN index: ${error.message}`);
         } finally {
           this._annWriting = false;
-        }
-      }
-    } catch (error) {
-      console.warn('[Cache] Failed to save cache:', error.message);
+        }
+      }
+      this.lastSaveError = null;
+    } catch (error) {
+      this.lastSaveError = error instanceof Error ? error : new Error(String(error));
+      console.warn('[Cache] Failed to save cache:', this.lastSaveError.message);
       
       if (
         this.config.vectorStoreFormat === 'binary' &&
@@ -1031,9 +1043,9 @@ export class EmbeddingsCache {
         }
       }
       
-      if (
-        this.config.vectorStoreFormat === 'sqlite' &&
-        !this.sqliteStore
+      if (
+        this.config.vectorStoreFormat === 'sqlite' &&
+        !this.sqliteStore
       ) {
         try {
           console.info('[Cache] Attempting to recover SQLite store after failed save...');
@@ -1043,14 +1055,19 @@ export class EmbeddingsCache {
           }
         } catch (recoverErr) {
           console.warn(`[Cache] Failed to recover SQLite store: ${recoverErr.message}`);
-          this.sqliteStore = null;
-        }
-      }
-    } finally {
-      this.isSaving = false;
-      this._saveInProgress = false; 
-    }
-  }
+          this.sqliteStore = null;
+        }
+      }
+      if (throwOnError) {
+        const wrapped = new Error(`Cache save failed: ${this.lastSaveError.message}`);
+        wrapped.cause = this.lastSaveError;
+        throw wrapped;
+      }
+    } finally {
+      this.isSaving = false;
+      this._saveInProgress = false; 
+    }
+  }
 
   
 

package/lib/vector-store-binary.js

@@ -14,30 +14,344 @@ const MAGIC_VECTORS = 'HMCV';
 const MAGIC_RECORDS = 'HMCR';
 const MAGIC_CONTENT = 'HMCC';
 
-const VECTORS_FILE = 'vectors.bin';
-const RECORDS_FILE = 'records.bin';
-const CONTENT_FILE = 'content.bin';
-const FILES_FILE = 'files.json';
-const RETRYABLE_RENAME_ERRORS = new Set(['EPERM', 'EACCES', 'EBUSY']);
-
-async function renameWithRetry(source, target, { retries = 5, delayMs = 50 } = {}) {
-  let attempt = 0;
-  let delay = delayMs;
-  while (true) {
-    try {
-      await fs.rename(source, target);
-      return;
-    } catch (err) {
-      const code = err?.code;
-      if (!RETRYABLE_RENAME_ERRORS.has(code) || attempt >= retries) {
-        throw err;
-      }
-      await new Promise((resolve) => setTimeout(resolve, delay));
-      attempt += 1;
-      delay *= 2;
-    }
-  }
-}
+const VECTORS_FILE = 'vectors.bin';
+const RECORDS_FILE = 'records.bin';
+const CONTENT_FILE = 'content.bin';
+const FILES_FILE = 'files.json';
+const TELEMETRY_FILE = 'binary-store-telemetry.json';
+const RETRYABLE_RENAME_ERRORS = new Set(['EPERM', 'EACCES', 'EBUSY']);
+const BINARY_ARTIFACT_BASE_FILES = [VECTORS_FILE, RECORDS_FILE, CONTENT_FILE, FILES_FILE];
+const STARTUP_TMP_CLEANUP_MIN_AGE_MS = 2 * 60 * 1000;
+const TELEMETRY_VERSION = 1;
+
+function createTelemetryTotals() {
+  return {
+    atomicReplaceAttempts: 0,
+    atomicReplaceSuccesses: 0,
+    atomicReplaceFailures: 0,
+    renameRetryCount: 0,
+    fallbackCopyCount: 0,
+    rollbackCount: 0,
+    rollbackRestoreFailureCount: 0,
+    startupCleanupRuns: 0,
+    staleTempFilesRemoved: 0,
+    staleTempFilesSkippedActive: 0,
+  };
+}
+
+function normalizeTelemetry(raw) {
+  const totals = createTelemetryTotals();
+  if (raw?.totals && typeof raw.totals === 'object') {
+    for (const key of Object.keys(totals)) {
+      if (Number.isFinite(raw.totals[key])) {
+        totals[key] = raw.totals[key];
+      }
+    }
+  }
+  return {
+    version: TELEMETRY_VERSION,
+    totals,
+    updatedAt: typeof raw?.updatedAt === 'string' ? raw.updatedAt : null,
+    lastError:
+      raw?.lastError && typeof raw.lastError === 'object'
+        ? {
+            at: typeof raw.lastError.at === 'string' ? raw.lastError.at : null,
+            message:
+              typeof raw.lastError.message === 'string' ? raw.lastError.message : null,
+          }
+        : null,
+    lastAtomicReplace:
+      raw?.lastAtomicReplace && typeof raw.lastAtomicReplace === 'object'
+        ? { ...raw.lastAtomicReplace }
+        : null,
+    lastStartupCleanup:
+      raw?.lastStartupCleanup && typeof raw.lastStartupCleanup === 'object'
+        ? { ...raw.lastStartupCleanup }
+        : null,
+  };
+}
+
+async function readTelemetryFile(cacheDir) {
+  const telemetryPath = path.join(cacheDir, TELEMETRY_FILE);
+  try {
+    const raw = await fs.readFile(telemetryPath, 'utf-8');
+    return normalizeTelemetry(JSON.parse(raw));
+  } catch {
+    return normalizeTelemetry(null);
+  }
+}
+
+async function writeTelemetryFile(cacheDir, telemetry) {
+  const telemetryPath = path.join(cacheDir, TELEMETRY_FILE);
+  await fs.mkdir(cacheDir, { recursive: true }).catch(() => {});
+  await fs.writeFile(telemetryPath, JSON.stringify(telemetry, null, 2));
+}
+
+async function updateTelemetry(cacheDir, mutate) {
+  if (!cacheDir) return;
+  try {
+    const telemetry = await readTelemetryFile(cacheDir);
+    mutate(telemetry);
+    telemetry.updatedAt = new Date().toISOString();
+    await writeTelemetryFile(cacheDir, telemetry);
+  } catch {
+    
+  }
+}
+
+function isProcessRunning(pid) {
+  if (!Number.isInteger(pid) || pid <= 0) return false;
+  try {
+    process.kill(pid, 0);
+    return true;
+  } catch (err) {
+    return err?.code === 'EPERM';
+  }
+}
+
+function parsePidFromBinaryArtifact(fileName) {
+  const match = fileName.match(/\.(?:tmp|bak)-(\d+)(?:-|$)/);
+  if (!match) return null;
+  const pid = Number.parseInt(match[1], 10);
+  return Number.isInteger(pid) ? pid : null;
+}
+
+function isBinaryTempArtifact(fileName) {
+  return BINARY_ARTIFACT_BASE_FILES.some(
+    (baseFile) =>
+      fileName.startsWith(`${baseFile}.tmp-`) || fileName.startsWith(`${baseFile}.bak-`)
+  );
+}
+
+function addToMetric(metrics, key, value = 1) {
+  if (!metrics || !Number.isFinite(value) || value <= 0) return;
+  metrics[key] = (metrics[key] || 0) + value;
+}
+
+export async function readBinaryStoreTelemetry(cacheDir) {
+  return readTelemetryFile(cacheDir);
+}
+
+export async function cleanupStaleBinaryArtifacts(
+  cacheDir,
+  { minAgeMs = STARTUP_TMP_CLEANUP_MIN_AGE_MS, logger = null } = {}
+) {
+  const result = {
+    cacheDir,
+    scanned: 0,
+    removed: 0,
+    skippedActive: 0,
+    removedFiles: [],
+  };
+
+  let entries = [];
+  try {
+    entries = await fs.readdir(cacheDir, { withFileTypes: true });
+  } catch {
+    return result;
+  }
+
+  const now = Date.now();
+  for (const entry of entries) {
+    const fileName = typeof entry === 'string' ? entry : entry?.name;
+    if (!fileName) continue;
+    const isFileEntry = typeof entry === 'string' ? true : entry?.isFile?.() === true;
+    if (!isFileEntry) continue;
+    if (!isBinaryTempArtifact(fileName)) continue;
+    result.scanned += 1;
+
+    const fullPath = path.join(cacheDir, fileName);
+    const stats = await fs.stat(fullPath).catch(() => null);
+    if (!stats) continue;
+
+    const ageMs = now - stats.mtimeMs;
+    const ownerPid = parsePidFromBinaryArtifact(fileName);
+    if (ownerPid && isProcessRunning(ownerPid)) {
+      result.skippedActive += 1;
+      continue;
+    }
+    if (ageMs < minAgeMs) continue;
+
+    await fs.rm(fullPath, { force: true }).catch(() => {});
+    result.removed += 1;
+    result.removedFiles.push(fileName);
+  }
+
+  await updateTelemetry(cacheDir, (telemetry) => {
+    telemetry.totals.startupCleanupRuns += 1;
+    telemetry.totals.staleTempFilesRemoved += result.removed;
+    telemetry.totals.staleTempFilesSkippedActive += result.skippedActive;
+    telemetry.lastStartupCleanup = {
+      at: new Date().toISOString(),
+      scanned: result.scanned,
+      removed: result.removed,
+      skippedActive: result.skippedActive,
+    };
+  });
+
+  if (logger && result.removed > 0) {
+    logger.info(
+      `[Cache] Startup temp cleanup removed ${result.removed} stale artifact(s) from ${cacheDir}`
+    );
+  }
+
+  return result;
+}
+
+function isRetryableRenameError(err) {
+  return RETRYABLE_RENAME_ERRORS.has(err?.code);
+}
+
+async function renameWithRetry(
+  source,
+  target,
+  { retries = 12, delayMs = 50, maxDelayMs = 1000 } = {}
+) {
+  let attempt = 0;
+  let delay = delayMs;
+  while (true) {
+    try {
+      await fs.rename(source, target);
+      return attempt;
+    } catch (err) {
+      if (!isRetryableRenameError(err) || attempt >= retries) {
+        err.renameRetryCount = attempt;
+        throw err;
+      }
+      await new Promise((resolve) => setTimeout(resolve, delay));
+      attempt += 1;
+      delay = Math.min(delay * 2, maxDelayMs);
+    }
+  }
+}
+
+async function pathExists(filePath) {
+  try {
+    await fs.access(filePath);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+async function removeIfExists(filePath) {
+  await fs.rm(filePath, { force: true }).catch(() => {});
+}
+
+async function promoteFileWithFallback(source, target, renameOptions = {}, metrics = null) {
+  try {
+    const retriesUsed = await renameWithRetry(source, target, renameOptions);
+    addToMetric(metrics, 'renameRetryCount', retriesUsed);
+    return;
+  } catch (renameError) {
+    const retriesUsed = Number.isFinite(renameError?.renameRetryCount)
+      ? renameError.renameRetryCount
+      : 0;
+    addToMetric(metrics, 'renameRetryCount', retriesUsed);
+    if (!isRetryableRenameError(renameError)) {
+      throw renameError;
+    }
+
+    try {
+      await fs.copyFile(source, target);
+      await removeIfExists(source);
+      addToMetric(metrics, 'fallbackCopyCount', 1);
+      return;
+    } catch (copyError) {
+      const wrapped = new Error(
+        `rename failed (${renameError.message}); fallback copy failed (${copyError.message})`
+      );
+      wrapped.code = copyError?.code || renameError?.code;
+      throw wrapped;
+    }
+  }
+}
+
+async function replaceFilesAtomically(filePairs, renameOptions = {}) {
+  const metrics = createTelemetryTotals();
+  metrics.atomicReplaceAttempts = 1;
+  const cacheDir = filePairs.length > 0 ? path.dirname(filePairs[0].target) : null;
+  const backupSuffix = `.bak-${process.pid}-${Date.now()}`;
+  const backups = [];
+  const replacedTargets = [];
+  let operationError = null;
+
+  try {
+    // Stage current files as backups first. If this fails, nothing is replaced.
+    for (const pair of filePairs) {
+      if (!(await pathExists(pair.target))) continue;
+      const backupPath = `${pair.target}${backupSuffix}`;
+      await removeIfExists(backupPath);
+      await promoteFileWithFallback(pair.target, backupPath, renameOptions, metrics);
+      backups.push({ target: pair.target, backupPath });
+    }
+
+    // Replace targets with new temp files.
+    for (const pair of filePairs) {
+      await promoteFileWithFallback(pair.source, pair.target, renameOptions, metrics);
+      replacedTargets.push(pair.target);
+    }
+    metrics.atomicReplaceSuccesses = 1;
+  } catch (error) {
+    operationError = error;
+    metrics.atomicReplaceFailures = 1;
+    metrics.rollbackCount = 1;
+    const rollbackErrors = [];
+
+    // Remove any partially replaced files before restoring backups.
+    for (const target of replacedTargets.reverse()) {
+      await removeIfExists(target);
+    }
+
+    // Restore original files from backups.
+    for (const backup of backups.reverse()) {
+      try {
+        await promoteFileWithFallback(backup.backupPath, backup.target, renameOptions, metrics);
+      } catch (restoreErr) {
+        rollbackErrors.push(
+          `restore ${path.basename(backup.target)} failed: ${restoreErr.message}`
+        );
+      }
+    }
+    if (rollbackErrors.length > 0) {
+      metrics.rollbackRestoreFailureCount = rollbackErrors.length;
+    }
+
+    // Clean up temp files left from this failed write attempt.
+    await Promise.all(filePairs.map((pair) => removeIfExists(pair.source)));
+
+    if (rollbackErrors.length > 0) {
+      error.message = `${error.message}. Rollback issues: ${rollbackErrors.join('; ')}`;
+    }
+    throw error;
+  } finally {
+    // Best-effort cleanup for any backup remnants after success/rollback.
+    await Promise.all(backups.map((backup) => removeIfExists(backup.backupPath)));
+    await updateTelemetry(cacheDir, (telemetry) => {
+      telemetry.totals.atomicReplaceAttempts += metrics.atomicReplaceAttempts;
+      telemetry.totals.atomicReplaceSuccesses += metrics.atomicReplaceSuccesses;
+      telemetry.totals.atomicReplaceFailures += metrics.atomicReplaceFailures;
+      telemetry.totals.renameRetryCount += metrics.renameRetryCount;
+      telemetry.totals.fallbackCopyCount += metrics.fallbackCopyCount;
+      telemetry.totals.rollbackCount += metrics.rollbackCount;
+      telemetry.totals.rollbackRestoreFailureCount += metrics.rollbackRestoreFailureCount;
+      telemetry.lastAtomicReplace = {
+        at: new Date().toISOString(),
+        success: metrics.atomicReplaceSuccesses > 0,
+        renameRetryCount: metrics.renameRetryCount,
+        fallbackCopyCount: metrics.fallbackCopyCount,
+        rollbackCount: metrics.rollbackCount,
+        rollbackRestoreFailureCount: metrics.rollbackRestoreFailureCount,
+      };
+      if (operationError) {
+        telemetry.lastError = {
+          at: new Date().toISOString(),
+          message: operationError.message,
+        };
+      }
+    });
+  }
+}
 
 function writeMagic(buffer, magic) {
   buffer.write(magic, 0, 'ascii');
@@ -433,18 +747,19 @@ export class BinaryVectorStore {
     return map;
   }
 
-  static async write(
-    cacheDir,
-    chunks,
-    {
+  static async write(
+    cacheDir,
+    chunks,
+    {
       contentCacheEntries,
       vectorCacheEntries,
-      vectorLoadMode,
-      getContent,
-      getVector,
-      preRename,
-    } = {}
-  ) {
+      vectorLoadMode,
+      getContent,
+      getVector,
+      preRename,
+      renameOptions,
+    } = {}
+  ) {
     ensureLittleEndian();
     const { vectorsPath, recordsPath, contentPath, filesPath } =
       BinaryVectorStore.getPaths(cacheDir);
@@ -611,15 +926,18 @@ export class BinaryVectorStore {
       await preRename();
     }
 
-    await Promise.all([
-      renameWithRetry(vectorsTmp, vectorsPath),
-      renameWithRetry(recordsTmp, recordsPath),
-      renameWithRetry(contentTmp, contentPath),
-      renameWithRetry(filesTmp, filesPath),
-    ]);
-
-    return BinaryVectorStore.load(cacheDir, {
-      contentCacheEntries,
+    await replaceFilesAtomically(
+      [
+        { source: vectorsTmp, target: vectorsPath },
+        { source: recordsTmp, target: recordsPath },
+        { source: contentTmp, target: contentPath },
+        { source: filesTmp, target: filesPath },
+      ],
+      renameOptions
+    );
+
+    return BinaryVectorStore.load(cacheDir, {
+      contentCacheEntries,
       vectorCacheEntries,
       vectorLoadMode,
     });

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@softerist/heuristic-mcp",
-  "version": "3.2.0",
+  "version": "3.2.2",
   "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",