@softerist/heuristic-mcp 3.2.1 → 3.2.3

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,65 @@ 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 (
+              (totals.corruptionDetected || 0) > 0 ||
+              (totals.corruptionAutoCleared || 0) > 0 ||
+              (totals.corruptionSecondaryReadonlyBlocked || 0) > 0
+            ) {
+              console.info(
+                `   Corruption telemetry: detected=${totals.corruptionDetected || 0} autoCleared=${totals.corruptionAutoCleared || 0} secondaryBlocked=${totals.corruptionSecondaryReadonlyBlocked || 0}`
+              );
+            }
+            if (binaryTelemetry.lastCorruption?.at || binaryTelemetry.lastCorruption?.message) {
+              const atLabel = binaryTelemetry.lastCorruption?.at
+                ? formatDateTime(binaryTelemetry.lastCorruption.at)
+                : 'unknown time';
+              const actionLabel =
+                typeof binaryTelemetry.lastCorruption?.action === 'string'
+                  ? binaryTelemetry.lastCorruption.action
+                  : 'unknown';
+              const contextLabel =
+                typeof binaryTelemetry.lastCorruption?.context === 'string'
+                  ? binaryTelemetry.lastCorruption.context
+                  : 'n/a';
+              const msgLabel =
+                typeof binaryTelemetry.lastCorruption?.message === 'string' &&
+                binaryTelemetry.lastCorruption.message.trim().length > 0
+                  ? ` message=${binaryTelemetry.lastCorruption.message}`
+                  : '';
+              console.info(
+                `   Last corruption event: ${atLabel} action=${actionLabel} context=${contextLabel}${msgLabel}`
+              );
+            }
+          }
+
           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, recordBinaryStoreCorruption } 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);
@@ -869,7 +879,25 @@ async function initialize(workspaceDir) {
         stopStartupMemory();
       }
     };
-    const tryAutoAttachWorkspaceCache = async (reason) => {
+    const handleCorruptCacheAfterLoad = async ({ context, canReindex }) => {
+      if (!cache.consumeAutoReindex()) return false;
+      cache.clearInMemoryState();
+      await recordBinaryStoreCorruption(config.cacheDirectory, {
+        context,
+        action: canReindex ? 'auto-cleared' : 'secondary-readonly-blocked',
+      });
+      if (canReindex) {
+        console.warn(
+          `[Server] Cache corruption detected while ${context}; in-memory cache was cleared and a full re-index will run.`
+        );
+      } 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.`
+        );
+      }
+      return true;
+    };
+    const tryAutoAttachWorkspaceCache = async (reason, { canReindex = workspaceLockAcquired } = {}) => {
       const candidate = await findAutoAttachWorkspaceCandidate({
         excludeCacheDirectory: config.cacheDirectory,
       });
@@ -883,7 +911,14 @@ 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();
+      await handleCorruptCacheAfterLoad({
+        context: `auto-attaching workspace cache (${reason})`,
+        canReindex,
+      });
       console.info(
         `[Server] Auto-attached workspace cache (${reason}): ${candidate.workspace} via ${candidate.source}`
       );
@@ -903,7 +938,9 @@ async function initialize(workspaceDir) {
         console.warn(
           `[Server] Detected system fallback workspace: ${config.searchDirectory}. Attempting cache auto-attach.`
         );
-        const attached = await tryAutoAttachWorkspaceCache('system-fallback');
+        const attached = await tryAutoAttachWorkspaceCache('system-fallback', {
+          canReindex: workspaceLockAcquired,
+        });
         if (!attached) {
           console.warn(
             '[Server] Waiting for a proper workspace root (MCP roots, env vars, or f_set_workspace).'
@@ -919,8 +956,12 @@ async function initialize(workspaceDir) {
       try {
         console.info('[Server] Secondary instance detected; loading cache in read-only mode.');
         await cache.load();
+        await handleCorruptCacheAfterLoad({
+          context: 'loading cache in secondary read-only mode',
+          canReindex: false,
+        });
         if (cache.getStoreSize() === 0) {
-          await tryAutoAttachWorkspaceCache('secondary-empty-cache');
+          await tryAutoAttachWorkspaceCache('secondary-empty-cache', { canReindex: false });
         }
         if (config.verbose) {
           logMemory('[Server] Memory (after cache load)');
@@ -934,9 +975,10 @@ async function initialize(workspaceDir) {
 
     void preloadEmbeddingModel();
 
-    try {
-      console.info('[Server] Loading cache (deferred)...');
+    try {
+      console.info('[Server] Loading cache (deferred)...');
       await cache.load();
+      await handleCorruptCacheAfterLoad({ context: 'startup cache load', canReindex: true });
       if (config.verbose) {
         logMemory('[Server] Memory (after cache load)');
       }
@@ -1092,6 +1134,22 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
     try {
       await fs.mkdir(config.cacheDirectory, { recursive: true });
       await cache.load();
+      if (cache.consumeAutoReindex()) {
+        cache.clearInMemoryState();
+        await recordBinaryStoreCorruption(config.cacheDirectory, {
+          context: 'f_set_workspace read-only attach',
+          action: 'secondary-readonly-blocked',
+        });
+        return {
+          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.`,
+            },
+          ],
+          isError: true,
+        };
+      }
       trustWorkspacePath(normalizedPath);
       return {
         content: [
@@ -1162,19 +1220,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

@@ -1,14 +1,18 @@
 import fs from 'fs/promises';
 import path from 'path';
-import { Worker } from 'worker_threads';
-import { StreamingJsonWriter } from './json-writer.js';
-import { BinaryVectorStore } from './vector-store-binary.js';
-import { SqliteVectorStore } from './vector-store-sqlite.js';
-import { isNonProjectDirectory } from './config.js';
+import { Worker } from 'worker_threads';
+import { StreamingJsonWriter } from './json-writer.js';
 import {
-  JSON_WORKER_THRESHOLD_BYTES,
-  ANN_DIMENSION_SAMPLE_SIZE,
-  HNSWLIB_ERROR_RESET_MS,
+  BinaryVectorStore,
+  BinaryStoreCorruptionError,
+  recordBinaryStoreCorruption,
+} from './vector-store-binary.js';
+import { SqliteVectorStore } from './vector-store-sqlite.js';
+import { isNonProjectDirectory } from './config.js';
+import {
+  JSON_WORKER_THRESHOLD_BYTES,
+  ANN_DIMENSION_SAMPLE_SIZE,
+  HNSWLIB_ERROR_RESET_MS,
   DEFAULT_READER_WAIT_TIMEOUT_MS,
 } from './constants.js';
 
@@ -270,6 +274,8 @@ export class EmbeddingsCache {
     this._saveTimer = null;
     this._saveRequested = false;
     this._savePromise = null;
+    this._saveThrowOnError = false;
+    this.lastSaveError = null;
 
     
     this.annIndex = null;
@@ -301,8 +307,23 @@ export class EmbeddingsCache {
     
     this._clearedAfterIndex = false;
     this._loadPromise = null;
+    this._corruptionDetected = false;
   }
 
+  /**
+   * Returns true if the last load() detected binary store corruption.
+   * Used by the server to decide whether to trigger an automatic re-index.
+   */
+  shouldAutoReindex() {
+    return this._corruptionDetected === true;
+  }
+
+  consumeAutoReindex() {
+    const should = this._corruptionDetected === true;
+    this._corruptionDetected = false;
+    return should;
+  }
+
   
   addInitError(stage, error) {
     this.initErrors.push({
@@ -508,6 +529,7 @@ export class EmbeddingsCache {
 
   async load({ forceVectorLoadMode } = {}) {
     if (!this.config.enableCache) return;
+    this._corruptionDetected = false;
 
     try {
       await fs.mkdir(this.config.cacheDirectory, { recursive: true });
@@ -658,7 +680,19 @@ export class EmbeddingsCache {
           });
         } catch (err) {
           this.binaryStore = null;
-          console.warn(`[Cache] Failed to load binary vector store: ${err.message}`);
+          const isCorruption = err instanceof BinaryStoreCorruptionError ||
+            err?.name === 'BinaryStoreCorruptionError';
+          if (isCorruption) {
+            console.warn(`[Cache] Binary store corruption detected: ${err.message}`);
+            this._corruptionDetected = true;
+            await recordBinaryStoreCorruption(this.config.cacheDirectory, {
+              message: err.message,
+              context: 'cache.load binary store',
+              action: 'detected',
+            });
+          } else {
+            console.warn(`[Cache] Failed to load binary vector store: ${err.message}`);
+          }
         }
       }
 
@@ -771,10 +805,13 @@ export class EmbeddingsCache {
 
   
 
-  save() {
+  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();
 
@@ -785,12 +822,17 @@ export class EmbeddingsCache {
     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();
+              await this.performSave({ throwOnError: rejectOnSaveError });
             }
           })
           .then(resolve, reject)
@@ -803,24 +845,24 @@ export class EmbeddingsCache {
     return this._savePromise;
   }
 
-  async performSave() {
-    
-    this._saveInProgress = true;
-    if (
-      this.config.allowSystemWorkspaceCache !== true &&
-      this.config.searchDirectory &&
-      isNonProjectDirectory(this.config.searchDirectory)
-    ) {
-      const source = this.config.workspaceResolution?.source || 'unknown';
-      console.warn(
-        `[Cache] Skipping cache save for non-project workspace (${source}): ${this.config.searchDirectory}`
-      );
-      this._saveInProgress = false;
-      return;
-    }
-
-    
-    if (this.activeReads > 0) {
+  async performSave({ throwOnError = false } = {}) {
+    
+    this._saveInProgress = true;
+    if (
+      this.config.allowSystemWorkspaceCache !== true &&
+      this.config.searchDirectory &&
+      isNonProjectDirectory(this.config.searchDirectory)
+    ) {
+      const source = this.config.workspaceResolution?.source || 'unknown';
+      console.warn(
+        `[Cache] Skipping cache save for non-project workspace (${source}): ${this.config.searchDirectory}`
+      );
+      this._saveInProgress = false;
+      return;
+    }
+
+    
+    if (this.activeReads > 0) {
       const timeoutMs = this.config.saveReaderWaitTimeoutMs ?? DEFAULT_READER_WAIT_TIMEOUT_MS;
       const allReadersFinished = await this.waitForReadersWithTimeout(timeoutMs);
       if (!allReadersFinished && !this.config.forceSaveWithActiveReaders) {
@@ -1011,8 +1053,10 @@ export class EmbeddingsCache {
           this._annWriting = false;
         }
       }
+      this.lastSaveError = null;
     } catch (error) {
-      console.warn('[Cache] Failed to save cache:', error.message);
+      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' &&
@@ -1046,6 +1090,11 @@ export class EmbeddingsCache {
           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;