@softerist/heuristic-mcp 3.0.17 → 3.1.0

package/index.js

@@ -7,11 +7,18 @@ import {
   ListToolsRequestSchema,
   ListResourcesRequestSchema,
   ReadResourceRequestSchema,
+  RootsListChangedNotificationSchema,
 } from '@modelcontextprotocol/sdk/types.js';
 let transformersModule = null;
 async function getTransformers() {
   if (!transformersModule) {
     transformersModule = await import('@huggingface/transformers');
+    if (transformersModule?.env) {
+      transformersModule.env.cacheDir = path.join(getGlobalCacheDir(), 'xenova');
+    }
+    if (transformersModule?.env) {
+      transformersModule.env.cacheDir = path.join(getGlobalCacheDir(), 'xenova');
+    }
   }
   return transformersModule;
 }
@@ -22,23 +29,25 @@ import path from 'path';
 import os from 'os';
 
 import { createRequire } from 'module';
-import { fileURLToPath } from 'url';
+import { fileURLToPath } from 'url';
+import { getWorkspaceCachePath } from './lib/workspace-cache-key.js';
+
 
-// Import package.json for version
 const require = createRequire(import.meta.url);
 const packageJson = require('./package.json');
 
-import { loadConfig, getGlobalCacheDir } from './lib/config.js';
+import { loadConfig, getGlobalCacheDir, isNonProjectDirectory } from './lib/config.js';
 import { clearStaleCaches } from './lib/cache-utils.js';
 import { enableStderrOnlyLogging, setupFileLogging, getLogFilePath } from './lib/logging.js';
 import { parseArgs, printHelp } from './lib/cli.js';
 import { clearCache } from './lib/cache-ops.js';
 import { logMemory, startMemoryLogger } from './lib/memory-logger.js';
-import {
-  registerSignalHandlers,
-  setupPidFile,
-  acquireWorkspaceLock,
-} from './lib/server-lifecycle.js';
+import {
+  registerSignalHandlers,
+  setupPidFile,
+  acquireWorkspaceLock,
+  stopOtherHeuristicServers,
+} from './lib/server-lifecycle.js';
 
 import { EmbeddingsCache } from './lib/cache.js';
 import { CodebaseIndexer } from './features/index-codebase.js';
@@ -116,17 +125,62 @@ async function printMemorySnapshot(workspaceDir) {
   return true;
 }
 
-// Arguments parsed in main()
 
-// Global state
-let embedder = null;
-let unloadMainEmbedder = null; // Function to unload the embedding model
-let cache = null;
-let indexer = null;
-let hybridSearch = null;
-let config = null;
-let setWorkspaceFeatureInstance = null;
-let autoWorkspaceSwitchPromise = null;
+
+
+let embedder = null;
+let unloadMainEmbedder = null; 
+let cache = null;
+let indexer = null;
+let hybridSearch = null;
+let config = null;
+let workspaceLockAcquired = true;
+let configReadyResolve = null;
+let configInitError = null;
+let configReadyPromise = new Promise((resolve) => {
+  configReadyResolve = resolve;
+});
+let setWorkspaceFeatureInstance = null;
+let autoWorkspaceSwitchPromise = null;
+let rootsCapabilitySupported = null;
+let rootsProbeInFlight = null;
+const WORKSPACE_BOUND_TOOL_NAMES = new Set([
+  'a_semantic_search',
+  'b_index_codebase',
+  'c_clear_cache',
+  'd_find_similar_code',
+  'd_ann_config',
+]);
+const trustedWorkspacePaths = new Set();
+
+function shouldRequireTrustedWorkspaceSignalForTool(toolName) {
+  return WORKSPACE_BOUND_TOOL_NAMES.has(toolName);
+}
+
+function trustWorkspacePath(workspacePath) {
+  const normalized = normalizePathForCompare(workspacePath);
+  if (normalized) {
+    trustedWorkspacePaths.add(normalized);
+  }
+}
+
+function isCurrentWorkspaceTrusted() {
+  if (!config?.searchDirectory) return false;
+  return trustedWorkspacePaths.has(normalizePathForCompare(config.searchDirectory));
+}
+
+function isToolResponseError(result) {
+  if (!result || typeof result !== 'object') return true;
+  if (result.isError === true) return true;
+  if (!Array.isArray(result.content)) return false;
+
+  return result.content.some(
+    (entry) =>
+      entry?.type === 'text' &&
+      typeof entry.text === 'string' &&
+      entry.text.trim().toLowerCase().startsWith('error:')
+  );
+}
 
 async function resolveWorkspaceFromEnvValue(rawValue) {
   if (!rawValue || rawValue.includes('${')) return null;
@@ -140,56 +194,272 @@ async function resolveWorkspaceFromEnvValue(rawValue) {
   }
 }
 
-async function detectRuntimeWorkspaceFromEnv() {
-  for (const key of getWorkspaceEnvKeys()) {
-    const workspacePath = await resolveWorkspaceFromEnvValue(process.env[key]);
+async function detectRuntimeWorkspaceFromEnv() {
+  for (const key of getWorkspaceEnvKeys()) {
+    const workspacePath = await resolveWorkspaceFromEnvValue(process.env[key]);
     if (workspacePath) {
       return { workspacePath, envKey: key };
     }
   }
 
-  return null;
-}
-
-async function maybeAutoSwitchWorkspace(request) {
-  if (process.env.VITEST === 'true' || process.env.NODE_ENV === 'test') return;
-  if (!setWorkspaceFeatureInstance || !config?.searchDirectory) return;
-  if (request?.params?.name === 'f_set_workspace') return;
+  return null;
+}
+
+function normalizePathForCompare(targetPath) {
+  if (!targetPath) return '';
+  const resolved = path.resolve(targetPath);
+  return process.platform === 'win32' ? resolved.toLowerCase() : resolved;
+}
+
+function isProcessAlive(pid) {
+  if (!Number.isInteger(pid) || pid <= 0) return false;
+  try {
+    process.kill(pid, 0);
+    return true;
+  } catch (err) {
+    return err?.code === 'EPERM';
+  }
+}
+
+async function findAutoAttachWorkspaceCandidate({ excludeCacheDirectory = null } = {}) {
+  const cacheRoot = path.join(getGlobalCacheDir(), 'heuristic-mcp');
+  const normalizedExclude = normalizePathForCompare(excludeCacheDirectory);
+
+  let cacheDirs = [];
+  try {
+    cacheDirs = await fs.readdir(cacheRoot, { withFileTypes: true });
+  } catch {
+    return null;
+  }
+
+  const candidatesByWorkspace = new Map();
+  const preferredWorkspaceFromEnv = (await detectRuntimeWorkspaceFromEnv())?.workspacePath ?? null;
+  const normalizedPreferred = normalizePathForCompare(preferredWorkspaceFromEnv);
+
+  const upsertCandidate = (candidate) => {
+    const key = normalizePathForCompare(candidate.workspace);
+    const existing = candidatesByWorkspace.get(key);
+    if (!existing || candidate.rank > existing.rank) {
+      candidatesByWorkspace.set(key, candidate);
+    }
+  };
+
+  for (const entry of cacheDirs) {
+    if (!entry.isDirectory()) continue;
+    const cacheDirectory = path.join(cacheRoot, entry.name);
+    if (normalizedExclude && normalizePathForCompare(cacheDirectory) === normalizedExclude) continue;
+
+    const lockPath = path.join(cacheDirectory, 'server.lock.json');
+    try {
+      const rawLock = await fs.readFile(lockPath, 'utf-8');
+      const lock = JSON.parse(rawLock);
+      if (!isProcessAlive(lock?.pid)) continue;
+      const workspace = path.resolve(lock?.workspace || '');
+      if (!workspace || isNonProjectDirectory(workspace)) continue;
+      const stats = await fs.stat(workspace).catch(() => null);
+      if (!stats?.isDirectory()) continue;
+      const rank = Date.parse(lock?.startedAt || '') || 0;
+      upsertCandidate({
+        workspace,
+        cacheDirectory,
+        source: `lock:${lock.pid}`,
+        rank,
+      });
+      continue;
+    } catch {
+      
+    }
+
+    const metaPath = path.join(cacheDirectory, 'meta.json');
+    try {
+      const rawMeta = await fs.readFile(metaPath, 'utf-8');
+      const meta = JSON.parse(rawMeta);
+      const workspace = path.resolve(meta?.workspace || '');
+      if (!workspace || isNonProjectDirectory(workspace)) continue;
+      const stats = await fs.stat(workspace).catch(() => null);
+      if (!stats?.isDirectory()) continue;
+      const filesIndexed = Number(meta?.filesIndexed || 0);
+      if (filesIndexed <= 0) continue;
+      const rank = Date.parse(meta?.lastSaveTime || '') || 0;
+      upsertCandidate({
+        workspace,
+        cacheDirectory,
+        source: 'meta',
+        rank,
+      });
+    } catch {
+      
+    }
+  }
+
+  const candidates = Array.from(candidatesByWorkspace.values());
+  if (candidates.length === 0) return null;
+  if (normalizedPreferred) {
+    const preferred = candidates.find(
+      (candidate) => normalizePathForCompare(candidate.workspace) === normalizedPreferred
+    );
+    if (preferred) return preferred;
+  }
+  if (candidates.length === 1) return candidates[0];
+  return null;
+}
+
+async function maybeAutoSwitchWorkspace(request) {
+  if (process.env.VITEST === 'true' || process.env.NODE_ENV === 'test') return null;
+  if (!setWorkspaceFeatureInstance || !config?.searchDirectory) return null;
+  if (request?.params?.name === 'f_set_workspace') return null;
+
+  const detected = await detectRuntimeWorkspaceFromEnv();
+  if (!detected) return null;
+  if (isNonProjectDirectory(detected.workspacePath)) {
+    console.info(
+      `[Server] Ignoring auto-switch candidate from env ${detected.envKey}: non-project path ${detected.workspacePath}`
+    );
+    return null;
+  }
+
+  const currentWorkspace = normalizePathForCompare(config.searchDirectory);
+  const detectedWorkspace = normalizePathForCompare(detected.workspacePath);
+  if (detectedWorkspace === currentWorkspace) return detected.workspacePath;
+
+  await maybeAutoSwitchWorkspaceToPath(detected.workspacePath, {
+    source: `env ${detected.envKey}`,
+    reindex: false,
+  });
+  return detected.workspacePath;
+}
+
+
+
+async function detectWorkspaceFromRoots({ quiet = false } = {}) {
+  try {
+    const caps = server.getClientCapabilities();
+    if (!caps?.roots) {
+      rootsCapabilitySupported = false;
+      if (!quiet) {
+        console.info(
+          '[Server] Client does not support roots capability, skipping workspace auto-detection.'
+        );
+      }
+      return null;
+    }
+    rootsCapabilitySupported = true;
+
+    const result = await server.listRoots();
+    if (!result?.roots?.length) {
+      if (!quiet) {
+        console.info('[Server] Client returned no roots.');
+      }
+      return null;
+    }
+
+    if (!quiet) {
+      console.info(`[Server] MCP roots received: ${result.roots.map(r => r.uri).join(', ')}`);
+    }
+
+    
+    const rootPaths = result.roots
+      .map(r => r.uri)
+      .filter(uri => uri.startsWith('file://'))
+      .map(uri => {
+        try {
+          return fileURLToPath(uri);
+        } catch {
+          return null;
+        }
+      })
+      .filter(Boolean);
+
+    if (rootPaths.length === 0) {
+      if (!quiet) {
+        console.info('[Server] No valid file:// roots found.');
+      }
+      return null;
+    }
+
+    return path.resolve(rootPaths[0]);
+  } catch (err) {
+    if (!quiet) {
+      console.warn(`[Server] MCP roots detection failed (non-fatal): ${err.message}`);
+    }
+    return null;
+  }
+}
+
+async function maybeAutoSwitchWorkspaceToPath(targetWorkspacePath, { source, reindex = false } = {}) {
+  if (!setWorkspaceFeatureInstance || !config?.searchDirectory) return;
+  if (!targetWorkspacePath) return;
+  if (isNonProjectDirectory(targetWorkspacePath)) {
+    if (config?.verbose) {
+      console.info(
+        `[Server] Ignoring auto-switch candidate from ${source || 'unknown'}: non-project path ${targetWorkspacePath}`
+      );
+    }
+    return;
+  }
+
+  const currentWorkspace = normalizePathForCompare(config.searchDirectory);
+  const targetWorkspace = normalizePathForCompare(targetWorkspacePath);
+  if (targetWorkspace === currentWorkspace) return;
+
+  if (autoWorkspaceSwitchPromise) {
+    await autoWorkspaceSwitchPromise;
+    return;
+  }
+
+  autoWorkspaceSwitchPromise = (async () => {
+    console.info(
+      `[Server] Auto-switching workspace from ${currentWorkspace} to ${targetWorkspacePath} (${source || 'auto'})`
+    );
+    const result = await setWorkspaceFeatureInstance.execute({
+      workspacePath: targetWorkspacePath,
+      reindex,
+    });
+    if (!result.success) {
+      console.warn(
+        `[Server] Auto workspace switch failed (${source || 'auto'}): ${result.error}`
+      );
+      return;
+    }
+    trustWorkspacePath(targetWorkspacePath);
+  })();
+
+  try {
+    await autoWorkspaceSwitchPromise;
+  } finally {
+    autoWorkspaceSwitchPromise = null;
+  }
+}
+
+async function maybeAutoSwitchWorkspaceFromRoots(request) {
+  if (process.env.VITEST === 'true' || process.env.NODE_ENV === 'test') return null;
+  if (!setWorkspaceFeatureInstance || !config?.searchDirectory) return null;
+  if (request?.params?.name === 'f_set_workspace') return null;
+  if (rootsCapabilitySupported === false) return null;
+
+  if (rootsProbeInFlight) {
+    return await rootsProbeInFlight;
+  }
+
+  rootsProbeInFlight = (async () => {
+    const rootWorkspace = await detectWorkspaceFromRoots({ quiet: true });
+    if (!rootWorkspace) return null;
+    await maybeAutoSwitchWorkspaceToPath(rootWorkspace, {
+      source: 'roots probe',
+      reindex: false,
+    });
+    return rootWorkspace;
+  })();
+
+  try {
+    return await rootsProbeInFlight;
+  } finally {
+    rootsProbeInFlight = null;
+  }
+}
 
-  const detected = await detectRuntimeWorkspaceFromEnv();
-  if (!detected) return;
-
-  const currentWorkspace = path.resolve(config.searchDirectory);
-  if (detected.workspacePath === currentWorkspace) return;
-
-  if (autoWorkspaceSwitchPromise) {
-    await autoWorkspaceSwitchPromise;
-    return;
-  }
-
-  autoWorkspaceSwitchPromise = (async () => {
-    console.info(
-      `[Server] Auto-switching workspace from ${currentWorkspace} to ${detected.workspacePath} (env ${detected.envKey})`
-    );
-    const result = await setWorkspaceFeatureInstance.execute({
-      workspacePath: detected.workspacePath,
-      reindex: false,
-    });
-    if (!result.success) {
-      console.warn(
-        `[Server] Auto workspace switch failed (env ${detected.envKey}): ${result.error}`
-      );
-    }
-  })();
 
-  try {
-    await autoWorkspaceSwitchPromise;
-  } finally {
-    autoWorkspaceSwitchPromise = null;
-  }
-}
 
-// Feature registry - ordered by priority (semantic_search first as primary tool)
 const features = [
   {
     module: HybridSearchFeature,
@@ -221,19 +491,22 @@ const features = [
     instance: null,
     handler: PackageVersionFeature.handleToolCall,
   },
-  {
-    module: SetWorkspaceFeature,
-    instance: null,
-    handler: null, // Late-bound after initialization
-  },
-];
+  {
+    module: SetWorkspaceFeature,
+    instance: null,
+    handler: null,
+  },
+];
 
-// Initialize application
-async function initialize(workspaceDir) {
-  // Load configuration with workspace support
+
+
+async function initialize(workspaceDir) {
+  
+  
   config = await loadConfig(workspaceDir);
   
-  // Automatic cache cleanup on startup (Option A)
+  
+  
   if (config.enableCache && config.cacheCleanup?.autoCleanup) {
     console.info('[Server] Running automatic cache cleanup...');
     const results = await clearStaleCaches({
@@ -245,7 +518,8 @@ async function initialize(workspaceDir) {
     }
   }
   
-  // Skip gc check during tests (VITEST env is set)
+  
+  
   const isTest = Boolean(process.env.VITEST || process.env.VITEST_WORKER_ID);
   if (config.enableExplicitGc && typeof global.gc !== 'function' && !isTest) {
     console.warn(
@@ -280,7 +554,8 @@ async function initialize(workspaceDir) {
         env.backends.onnx.wasm.numThreads = ONNX_THREAD_LIMIT;
       }
     } catch {
-      // ignore: fallback tuning is best effort
+      
+      
     }
     const status = getNativeOnnxStatus();
     const reason = status?.message || 'onnxruntime-node not available';
@@ -295,27 +570,101 @@ async function initialize(workspaceDir) {
       config.embeddingProcessPerBatch = true;
     }
   }
-  const lock = await acquireWorkspaceLock({
-    cacheDirectory: config.cacheDirectory,
-    workspaceDir: config.searchDirectory,
-  });
-  if (!lock.acquired) {
-    console.warn(
-      `[Server] Another heuristic-mcp instance is already running for this workspace (pid ${lock.ownerPid ?? 'unknown'}).`
-    );
-    console.warn('[Server] Exiting to avoid duplicate model loads.');
-    process.exit(0);
-  }
-  const [pidPath, logPath] = await Promise.all([
-    setupPidFile({ pidFileName: PID_FILE_NAME, cacheDirectory: config.cacheDirectory }),
-    setupFileLogging(config),
-  ]);
+  const resolutionSource = config.workspaceResolution?.source || 'unknown';
+  if (resolutionSource === 'workspace-arg' || resolutionSource === 'env') {
+    trustWorkspacePath(config.searchDirectory);
+  }
+  const isSystemFallbackWorkspace =
+    (resolutionSource === 'cwd' || resolutionSource === 'cwd-root-search') &&
+    isNonProjectDirectory(config.searchDirectory);
+
+  let pidPath = null;
+  let logPath = null;
+  if (isSystemFallbackWorkspace) {
+    workspaceLockAcquired = false;
+    console.warn(
+      `[Server] System fallback workspace detected (${config.searchDirectory}); running in lightweight read-only mode.`
+    );
+    console.warn('[Server] Skipping lock/PID/log file setup for fallback workspace.');
+  } else {
+    if (config.autoStopOtherServersOnStartup !== false) {
+      const globalCacheRoot = path.join(getGlobalCacheDir(), 'heuristic-mcp');
+      const { killed, failed } = await stopOtherHeuristicServers({
+        globalCacheRoot,
+        currentCacheDirectory: config.cacheDirectory,
+      });
+      if (killed.length > 0) {
+        const details = killed
+          .map((entry) => `${entry.pid}${entry.workspace ? ` (${entry.workspace})` : ''}`)
+          .join(', ');
+        console.info(`[Server] Auto-stopped ${killed.length} stale heuristic-mcp server(s): ${details}`);
+      }
+      if (failed.length > 0) {
+        const details = failed
+          .map((entry) => `${entry.pid}${entry.workspace ? ` (${entry.workspace})` : ''}`)
+          .join(', ');
+        console.warn(
+          `[Server] Failed to stop ${failed.length} older heuristic-mcp server(s): ${details}`
+        );
+      }
+    }
+
+    const lock = await acquireWorkspaceLock({
+      cacheDirectory: config.cacheDirectory,
+      workspaceDir: config.searchDirectory,
+    });
+    workspaceLockAcquired = lock.acquired;
+    if (!workspaceLockAcquired) {
+      console.warn(
+        `[Server] Another heuristic-mcp instance is already running for this workspace (pid ${lock.ownerPid ?? 'unknown'}).`
+      );
+      console.warn(
+        '[Server] Starting in secondary read-only mode: background indexing and cache writes are disabled for this instance.'
+      );
+    }
+    [pidPath, logPath] = workspaceLockAcquired
+      ? await Promise.all([
+          setupPidFile({ pidFileName: PID_FILE_NAME, cacheDirectory: config.cacheDirectory }),
+          setupFileLogging(config),
+        ])
+      : [null, await setupFileLogging(config)];
+  }
   if (logPath) {
     console.info(`[Logs] Writing server logs to ${logPath}`);
     console.info(`[Logs] Log viewer: heuristic-mcp --logs --workspace "${config.searchDirectory}"`);
   }
+  {
+    const resolution = config.workspaceResolution || {};
+    const sourceLabel =
+      resolution.source === 'env' && resolution.envKey
+        ? `env:${resolution.envKey}`
+        : resolution.source || 'unknown';
+    const baseLabel = resolution.baseDirectory || '(unknown)';
+    const searchLabel = resolution.searchDirectory || config.searchDirectory;
+    const overrideLabel = resolution.searchDirectoryFromConfig ? 'yes' : 'no';
+    console.info(
+      `[Server] Workspace resolved: source=${sourceLabel}, base=${baseLabel}, search=${searchLabel}, configOverride=${overrideLabel}`
+    );
+    if (resolution.fromPath) {
+      console.info(`[Server] Workspace resolution origin cwd: ${resolution.fromPath}`);
+    }
+
+    const workspaceEnvProbe = Array.isArray(resolution.workspaceEnvProbe)
+      ? resolution.workspaceEnvProbe
+      : [];
+    if (workspaceEnvProbe.length > 0) {
+      const probePreview = workspaceEnvProbe.slice(0, 8).map((entry) => {
+        const scope = entry?.priority ? 'priority' : 'diagnostic';
+        const status = entry?.resolvedPath ? `valid:${entry.resolvedPath}` : `invalid:${entry?.value}`;
+        return `${entry?.key}[${scope}]=${status}`;
+      });
+      const suffix = workspaceEnvProbe.length > 8 ? ` (+${workspaceEnvProbe.length - 8} more)` : '';
+      console.info(`[Server] Workspace env probe: ${probePreview.join('; ')}${suffix}`);
+    }
+  }
 
-  // Log effective configuration for debugging
+  
+  
   console.info(
     `[Server] Config: workerThreads=${config.workerThreads}, embeddingProcessPerBatch=${config.embeddingProcessPerBatch}`
   );
@@ -327,14 +676,17 @@ async function initialize(workspaceDir) {
     console.info(`[Server] PID file: ${pidPath}`);
   }
 
-  // Log cache directory logic for debugging
+  
+  
   try {
     const globalCache = path.join(getGlobalCacheDir(), 'heuristic-mcp');
     const localCache = path.join(process.cwd(), '.heuristic-mcp');
     console.info(`[Server] Cache debug: Global=${globalCache}, Local=${localCache}`);
     console.info(`[Server] Process CWD: ${process.cwd()}`);
+    console.info(`[Server] Resolved workspace: ${config.searchDirectory} (via ${config.workspaceResolution?.source || 'unknown'})`);
   } catch (_e) {
-    /* ignore */
+    
+    
   }
 
   let stopStartupMemory = null;
@@ -343,7 +695,8 @@ async function initialize(workspaceDir) {
     stopStartupMemory = startMemoryLogger('[Server] Memory (startup)', MEMORY_LOG_INTERVAL_MS);
   }
 
-  // Ensure search directory exists
+  
+  
   try {
     await fs.access(config.searchDirectory);
   } catch {
@@ -351,7 +704,8 @@ async function initialize(workspaceDir) {
     process.exit(1);
   }
 
-  // Create a transparent lazy-loading embedder closure
+  
+  
   console.info('[Server] Initializing features...');
   let cachedEmbedderPromise = null;
   const lazyEmbedder = async (...args) => {
@@ -384,7 +738,7 @@ async function initialize(workspaceDir) {
     return model(...args);
   };
   
-  // Unload the main process embedding model to free memory
+  
   const unloader = async () => {
     if (!cachedEmbedderPromise) return false;
     try {
@@ -409,7 +763,7 @@ async function initialize(workspaceDir) {
   };
   
   embedder = lazyEmbedder;
-  unloadMainEmbedder = unloader; // Store in module scope for tool handler access
+  unloadMainEmbedder = unloader; 
   const preloadEmbeddingModel = async () => {
     if (config.preloadEmbeddingModel === false) return;
     try {
@@ -420,29 +774,29 @@ async function initialize(workspaceDir) {
     }
   };
 
-  // NOTE: We no longer auto-load in verbose mode when preloadEmbeddingModel=false.
-  // The model will be loaded lazily on first search or by child processes during indexing.
+  
+  
 
-  // Initialize cache (load deferred until after server is ready)
+  
   cache = new EmbeddingsCache(config);
   console.info(`[Server] Cache directory: ${config.cacheDirectory}`);
 
-  // Initialize features
+  
   indexer = new CodebaseIndexer(embedder, cache, config, server);
   hybridSearch = new HybridSearch(embedder, cache, config);
   const cacheClearer = new ClearCacheFeature.CacheClearer(embedder, cache, config, indexer);
   const findSimilarCode = new FindSimilarCodeFeature.FindSimilarCode(embedder, cache, config);
   const annConfig = new AnnConfigFeature.AnnConfigTool(cache, config);
 
-  // Store feature instances (matches features array order)
+  
   features[0].instance = hybridSearch;
   features[1].instance = indexer;
   features[2].instance = cacheClearer;
   features[3].instance = findSimilarCode;
   features[4].instance = annConfig;
-  // Features 5 (PackageVersion) doesn't need instance
+  
 
-  // Initialize SetWorkspace feature with shared state
+  
   const setWorkspaceInstance = new SetWorkspaceFeature.SetWorkspaceFeature(
     config,
     cache,
@@ -453,34 +807,99 @@ async function initialize(workspaceDir) {
   features[6].instance = setWorkspaceInstance;
   features[6].handler = SetWorkspaceFeature.createHandleToolCall(setWorkspaceInstance);
 
-  // Attach hybridSearch to server for cross-feature access (e.g. cache invalidation)
-  server.hybridSearch = hybridSearch;
-
-  const startBackgroundTasks = async () => {
-    // Keep startup responsive: do not block server readiness on model preload.
-    void preloadEmbeddingModel();
-
+  
+  server.hybridSearch = hybridSearch;
+
+  const startBackgroundTasks = async () => {
+    const stopStartupMemoryLogger = () => {
+      if (stopStartupMemory) {
+        stopStartupMemory();
+      }
+    };
+    const tryAutoAttachWorkspaceCache = async (reason) => {
+      const candidate = await findAutoAttachWorkspaceCandidate({
+        excludeCacheDirectory: config.cacheDirectory,
+      });
+      if (!candidate) {
+        console.warn(
+          `[Server] Auto-attach skipped (${reason}): no unambiguous workspace cache candidate found.`
+        );
+        return false;
+      }
+
+      config.searchDirectory = candidate.workspace;
+      config.cacheDirectory = candidate.cacheDirectory;
+      await fs.mkdir(config.cacheDirectory, { recursive: true });
+      await cache.load();
+      console.info(
+        `[Server] Auto-attached workspace cache (${reason}): ${candidate.workspace} via ${candidate.source}`
+      );
+      if (config.verbose) {
+        logMemory('[Server] Memory (after cache load)');
+      }
+      return true;
+    };
+
+    const resolutionSource = config.workspaceResolution?.source || 'unknown';
+    const isSystemFallback =
+      (resolutionSource === 'cwd' || resolutionSource === 'cwd-root-search') &&
+      isNonProjectDirectory(config.searchDirectory);
+
+    if (isSystemFallback) {
+      try {
+        console.warn(
+          `[Server] Detected system fallback workspace: ${config.searchDirectory}. Attempting cache auto-attach.`
+        );
+        const attached = await tryAutoAttachWorkspaceCache('system-fallback');
+        if (!attached) {
+          console.warn(
+            '[Server] Waiting for a proper workspace root (MCP roots, env vars, or f_set_workspace).'
+          );
+        }
+      } finally {
+        stopStartupMemoryLogger();
+      }
+      return;
+    }
+
+    if (!workspaceLockAcquired) {
+      try {
+        console.info('[Server] Secondary instance detected; loading cache in read-only mode.');
+        await cache.load();
+        if (cache.getStoreSize() === 0) {
+          await tryAutoAttachWorkspaceCache('secondary-empty-cache');
+        }
+        if (config.verbose) {
+          logMemory('[Server] Memory (after cache load)');
+        }
+      } finally {
+        stopStartupMemoryLogger();
+      }
+      console.info('[Server] Secondary instance ready; skipping background indexing.');
+      return;
+    }
+
+    void preloadEmbeddingModel();
+
     try {
       console.info('[Server] Loading cache (deferred)...');
-      await cache.load();
-      if (config.verbose) {
-        logMemory('[Server] Memory (after cache load)');
-      }
-    } finally {
-      if (stopStartupMemory) {
-        stopStartupMemory();
-      }
-    }
-
-    // Start indexing in background (non-blocking)
+      await cache.load();
+      if (config.verbose) {
+        logMemory('[Server] Memory (after cache load)');
+      }
+    } finally {
+      stopStartupMemoryLogger();
+    }
+
+    
     console.info('[Server] Starting background indexing (delayed)...');
 
-    // Slight delay to allow server to bind and accept first request if immediate
+    
     setTimeout(() => {
       indexer
         .indexAll()
         .then(() => {
-          // Only start file watcher if explicitly enabled in config
+          
           if (config.watchFiles) {
             indexer.setupFileWatcher();
           }
@@ -494,7 +913,7 @@ async function initialize(workspaceDir) {
   return { startBackgroundTasks, config };
 }
 
-// Setup MCP server
+
 const server = new Server(
   {
     name: 'heuristic-mcp',
@@ -508,19 +927,46 @@ const server = new Server(
   }
 );
 
-// Handle resources/list
-server.setRequestHandler(ListResourcesRequestSchema, async () => {
-  return await handleListResources(config);
-});
 
-// Handle resources/read
-server.setRequestHandler(ReadResourceRequestSchema, async (request) => {
-  return await handleReadResource(request.params.uri, config);
-});
+server.setNotificationHandler(RootsListChangedNotificationSchema, async () => {
+  console.info('[Server] Received roots/list_changed notification from client.');
+  const newRoot = await detectWorkspaceFromRoots();
+  if (newRoot) {
+    await maybeAutoSwitchWorkspaceToPath(newRoot, {
+      source: 'roots changed',
+      reindex: true,
+    });
+  }
+});
+
+
 
-// Register tools from all features
-server.setRequestHandler(ListToolsRequestSchema, async () => {
-  const tools = [];
+server.setRequestHandler(ListResourcesRequestSchema, async () => {
+  await configReadyPromise;
+  if (configInitError || !config) {
+    throw configInitError ?? new Error('Server configuration is not initialized');
+  }
+  return await handleListResources(config);
+});
+
+
+
+server.setRequestHandler(ReadResourceRequestSchema, async (request) => {
+  await configReadyPromise;
+  if (configInitError || !config) {
+    throw configInitError ?? new Error('Server configuration is not initialized');
+  }
+  return await handleReadResource(request.params.uri, config);
+});
+
+
+
+server.setRequestHandler(ListToolsRequestSchema, async () => {
+  await configReadyPromise;
+  if (configInitError || !config) {
+    throw configInitError ?? new Error('Server configuration is not initialized');
+  }
+  const tools = [];
 
   for (const feature of features) {
     const toolDef = feature.module.getToolDefinition(config);
@@ -530,15 +976,142 @@ server.setRequestHandler(ListToolsRequestSchema, async () => {
   return { tools };
 });
 
-// Handle tool calls
-server.setRequestHandler(CallToolRequestSchema, async (request) => {
-  await maybeAutoSwitchWorkspace(request);
 
-  for (const feature of features) {
+
+server.setRequestHandler(CallToolRequestSchema, async (request) => {
+  await configReadyPromise;
+  if (configInitError || !config) {
+    return {
+      content: [
+        {
+          type: 'text',
+          text: `Server initialization failed: ${configInitError?.message || 'configuration not available'}`,
+        },
+      ],
+      isError: true,
+    };
+  }
+
+  if (!workspaceLockAcquired && request.params?.name === 'f_set_workspace') {
+    const args = request.params?.arguments || {};
+    const workspacePath = args.workspacePath;
+    const reindex = args.reindex !== false;
+    if (typeof workspacePath !== 'string' || workspacePath.trim().length === 0) {
+      return {
+        content: [{ type: 'text', text: 'Error: workspacePath is required.' }],
+        isError: true,
+      };
+    }
+    if (reindex) {
+      return {
+        content: [
+          {
+            type: 'text',
+            text: 'This server instance is in secondary read-only mode. Set reindex=false to attach cache only.',
+          },
+        ],
+        isError: true,
+      };
+    }
+    const normalizedPath = path.resolve(workspacePath);
+    try {
+      const stats = await fs.stat(normalizedPath);
+      if (!stats.isDirectory()) {
+        return {
+          content: [{ type: 'text', text: `Error: Path is not a directory: ${normalizedPath}` }],
+          isError: true,
+        };
+      }
+    } catch (err) {
+      return {
+        content: [
+          {
+            type: 'text',
+            text: `Error: Cannot access directory ${normalizedPath}: ${err.message}`,
+          },
+        ],
+        isError: true,
+      };
+    }
+
+    config.searchDirectory = normalizedPath;
+    config.cacheDirectory = getWorkspaceCachePath(normalizedPath, getGlobalCacheDir());
+    try {
+      await fs.mkdir(config.cacheDirectory, { recursive: true });
+      await cache.load();
+      trustWorkspacePath(normalizedPath);
+      return {
+        content: [
+          {
+            type: 'text',
+            text: `Attached in read-only mode to workspace cache: ${normalizedPath}`,
+          },
+        ],
+      };
+    } catch (err) {
+      return {
+        content: [
+          {
+            type: 'text',
+            text: `Error: Failed to attach cache for ${normalizedPath}: ${err.message}`,
+          },
+        ],
+        isError: true,
+      };
+    }
+  }
+
+  if (
+    !workspaceLockAcquired &&
+    ['b_index_codebase', 'c_clear_cache'].includes(request.params?.name)
+  ) {
+    return {
+      content: [
+        {
+          type: 'text',
+          text: 'This server instance is in secondary read-only mode. Use the primary instance for indexing/cache mutation tools.',
+        },
+      ],
+      isError: true,
+    };
+  }
+  const detectedFromRoots = await maybeAutoSwitchWorkspaceFromRoots(request);
+  const detectedFromEnv = await maybeAutoSwitchWorkspace(request);
+  if (detectedFromRoots) {
+    trustWorkspacePath(detectedFromRoots);
+  }
+  if (detectedFromEnv) {
+    trustWorkspacePath(detectedFromEnv);
+  }
+
+  const toolName = request.params?.name;
+  if (
+    config.requireTrustedWorkspaceSignalForTools === true &&
+    shouldRequireTrustedWorkspaceSignalForTool(toolName) &&
+    !detectedFromRoots &&
+    !detectedFromEnv &&
+    !isCurrentWorkspaceTrusted()
+  ) {
+    return {
+      content: [
+        {
+          type: 'text',
+          text:
+            `Workspace context appears stale for "${toolName}" (current: "${config.searchDirectory}"). ` +
+            'Please reload your IDE window and retry. ' +
+            'If needed, call MCP tool "f_set_workspace" from your chat/client with your opened folder path.',
+        },
+      ],
+      isError: true,
+    };
+  }
+
+  for (const feature of features) {
     const toolDef = feature.module.getToolDefinition(config);
 
     if (request.params.name === toolDef.name) {
-      // Safety check: handler may be null if initialization is incomplete
+      
+      
       if (typeof feature.handler !== 'function') {
         return {
           content: [{
@@ -547,14 +1120,20 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
           }],
           isError: true,
         };
-      }
-      const result = await feature.handler(request, feature.instance);
+      }
+      const result = await feature.handler(request, feature.instance);
+      if (toolDef.name === 'f_set_workspace' && !isToolResponseError(result)) {
+        trustWorkspacePath(config.searchDirectory);
+      }
+      
+      
+      
+      
       
-      // Unload embedding model after search-related tools to free memory
-      // Tools that use embedder: a_semantic_search, d_find_similar_code
       const searchTools = ['a_semantic_search', 'd_find_similar_code'];
       if (config.unloadModelAfterSearch && searchTools.includes(toolDef.name)) {
-        // Defer unload slightly to not block response, use setImmediate for non-blocking
+        
+        
         setImmediate(async () => {
           if (typeof unloadMainEmbedder === 'function') {
             await unloadMainEmbedder();
@@ -577,7 +1156,8 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
   };
 });
 
-// Main entry point
+
+
 export async function main(argv = process.argv) {
   const parsed = parseArgs(argv);
   const {
@@ -641,19 +1221,23 @@ export async function main(argv = process.argv) {
     process.exit(0);
   }
 
-  // --cache command (cache-only, no server status)
+  
+  
   if (wantsCache) {
     await status({ fix: wantsClean, cacheOnly: true, workspaceDir });
     process.exit(0);
   }
 
-  // --clear <cache_id> command (remove specific cache by ID)
+  
+  
   const clearIndex = parsed.rawArgs.indexOf('--clear');
   if (clearIndex !== -1) {
     const cacheId = parsed.rawArgs[clearIndex + 1];
     if (cacheId && !cacheId.startsWith('--')) {
-      // Remove specific cache by ID
-      // Determine platform-appropriate cache directory
+      
+      
+      
+      
       let cacheHome;
       if (process.platform === 'win32') {
         cacheHome = process.env.LOCALAPPDATA || path.join(os.homedir(), 'AppData', 'Local');
@@ -697,7 +1281,8 @@ export async function main(argv = process.argv) {
       }
       process.exit(0);
     }
-    // If --clear with no arg, fall through to --clear-cache behavior
+    
+    
   }
 
   if (wantsClearCache) {
@@ -740,34 +1325,88 @@ export async function main(argv = process.argv) {
   }
 
   registerSignalHandlers(requestShutdown);
-  // NOTE: We intentionally do NOT shut down on stdin close.
-  // When an IDE restarts, it may briefly close stdin then reconnect.
-  // The server should remain running to preserve cache and be ready for reconnection.
-  // Use SIGINT/SIGTERM or --stop command for intentional shutdown.
-  const { startBackgroundTasks } = await initialize(workspaceDir);
+  
+  
+  
+  
 
-  // (Blocking init moved below)
+  
+  const detectedRootPromise = 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 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');
+      }
+    });
+  }
+
+  
+  
+  const detectedRoot = await detectedRootPromise;
 
-  const transport = new StdioServerTransport();
-  await server.connect(transport);
+  
+  const effectiveWorkspace = detectedRoot || workspaceDir;
+  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;
 
-  console.info('[Server] MCP transport connected.');
   console.info('[Server] Heuristic MCP server started.');
 
-  // Load cache and start indexing in background AFTER server is ready
+  
+  
   void startBackgroundTasks().catch((err) => {
     console.error(`[Server] Background task error: ${err.message}`);
   });
   console.info('[Server] MCP server is now fully ready to accept requests.');
 }
 
-// Graceful shutdown
+
+
 async function gracefulShutdown(signal) {
   console.info(`[Server] Received ${signal}, shutting down gracefully...`);
 
   const cleanupTasks = [];
 
-  // Stop file watcher
+  
+  
   if (indexer && indexer.watcher) {
     cleanupTasks.push(
       indexer.watcher
@@ -777,7 +1416,8 @@ async function gracefulShutdown(signal) {
     );
   }
 
-  // Give workers time to finish current batch
+  
+  
   if (indexer && indexer.terminateWorkers) {
     cleanupTasks.push(
       (async () => {
@@ -788,20 +1428,26 @@ async function gracefulShutdown(signal) {
     );
   }
 
-  // Save cache
-  if (cache) {
-    cleanupTasks.push(
-      cache
-        .save()
-        .then(() => console.info('[Server] Cache saved'))
-        .catch((err) => console.error(`[Server] Failed to save cache: ${err.message}`))
-    );
-  }
+  
+  
+  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}`))
+      );
+    }
+  }
 
   await Promise.allSettled(cleanupTasks);
   console.info('[Server] Goodbye!');
 
-  // Allow stdio buffers to flush
+  
+  
   setTimeout(() => process.exit(0), 100);
 }