@softerist/heuristic-mcp 3.0.16 → 3.1.0

package/lib/cli.js

@@ -1,10 +1,33 @@
 export const DEFAULT_LOG_TAIL_LINES = 200;
+const FLAG_ARGS_WITH_VALUES = new Set(['--tail', '--workspace', '--start', '--register', '--clear']);
+const COMMAND_ALIASES = Object.freeze({
+  status: '--status',
+  stat: '--status',
+  log: '--logs',
+  logs: '--logs',
+  start: '--start',
+  stop: '--stop',
+  cache: '--cache',
+  'clear-cache': '--clear-cache',
+  clearcache: '--clear-cache',
+  clear: '--clear',
+  clean: '--clear',
+  mem: '--mem',
+  memory: '--mem',
+  version: '--version',
+  help: '--help',
+  register: '--register',
+});
+const FLAG_ALIASES = Object.freeze({
+  '--log': '--logs',
+});
 
 export function printHelp(defaultTailLines = DEFAULT_LOG_TAIL_LINES) {
   console.info(`Heuristic MCP Server
 
 Usage:
   heuristic-mcp [options]
+  heuristic-mcp <command> [args]
 
 Options:
   --cache                  Show cache status and cleanup recommendations (dry-run)
@@ -21,33 +44,97 @@ Options:
   --workspace <path>       Workspace path (used by IDE launch / log viewer)
   --version, -v            Show version
   --help, -h               Show this help
+
 `);
 }
 
-export function parseWorkspaceDir(args) {
-  const workspaceIndex = args.findIndex((arg) => arg.startsWith('--workspace'));
-  if (workspaceIndex === -1) return null;
+export function normalizeCliArgs(rawArgs = []) {
+  const normalized = [];
+  let expectsValue = false;
 
-  const arg = args[workspaceIndex];
-  let rawWorkspace = null;
+  for (const token of rawArgs) {
+    if (expectsValue) {
+      normalized.push(token);
+      expectsValue = false;
+      continue;
+    }
 
-  if (arg.includes('=')) {
-    rawWorkspace = arg.split('=')[1];
-  } else if (workspaceIndex + 1 < args.length) {
-    rawWorkspace = args[workspaceIndex + 1];
-  }
+    if (token.startsWith('--')) {
+      const eqIdx = token.indexOf('=');
+      if (eqIdx !== -1) {
+        const flagPart = token.slice(0, eqIdx);
+        const valuePart = token.slice(eqIdx + 1);
+        const mappedFlag = FLAG_ALIASES[flagPart] || flagPart;
+        normalized.push(`${mappedFlag}=${valuePart}`);
+        continue;
+      }
+
+      const mappedFlag = FLAG_ALIASES[token] || token;
+      normalized.push(mappedFlag);
+      if (FLAG_ARGS_WITH_VALUES.has(mappedFlag)) {
+        expectsValue = true;
+      }
+      continue;
+    }
+
+    if (token.startsWith('-')) {
+      normalized.push(token);
+      continue;
+    }
+
+    const mappedCommand = COMMAND_ALIASES[token.toLowerCase()];
+    if (mappedCommand) {
+      normalized.push(mappedCommand);
+      if (FLAG_ARGS_WITH_VALUES.has(mappedCommand)) {
+        expectsValue = true;
+      }
+      continue;
+    }
 
-  // Check if IDE variable wasn't expanded (contains ${})
-  if (rawWorkspace && rawWorkspace.includes('${')) {
-    console.error(
-      `[Server] IDE variable not expanded: ${rawWorkspace}, falling back to auto-detected workspace`
-    );
-    return null;
+    normalized.push(token);
   }
 
-  return rawWorkspace || null;
+  return normalized;
+}
+
+export function shouldDefaultToHelp(
+  args,
+  runtime = { stdinIsTTY: process.stdin.isTTY, stdoutIsTTY: process.stdout.isTTY }
+) {
+  return args.length === 0 && Boolean(runtime.stdinIsTTY && runtime.stdoutIsTTY);
 }
 
+export function parseWorkspaceDir(args) {
+  const isUnexpandedWorkspaceValue = (value) =>
+    value.includes('${') || /\{\{.+\}\}/.test(value) || /%[A-Za-z_][A-Za-z0-9_]*%/.test(value);
+
+  for (let i = 0; i < args.length; i += 1) {
+    const arg = args[i];
+    if (!arg.startsWith('--workspace')) continue;
+
+    let rawWorkspace = null;
+    if (arg.startsWith('--workspace=')) {
+      rawWorkspace = arg.slice('--workspace='.length);
+    } else if (arg === '--workspace' && i + 1 < args.length) {
+      rawWorkspace = args[i + 1];
+      i += 1;
+    }
+
+    if (!rawWorkspace) continue;
+
+    if (isUnexpandedWorkspaceValue(rawWorkspace)) {
+      console.error(
+        `[Server] IDE variable not expanded: ${rawWorkspace}, falling back to next workspace candidate`
+      );
+      continue;
+    }
+
+    return rawWorkspace;
+  }
+
+  return null;
+}
+
 export function collectUnknownFlags(rawArgs, knownFlags, flagsWithValue) {
   const unknownFlags = [];
   for (let i = 0; i < rawArgs.length; i += 1) {
@@ -67,12 +154,15 @@ export function collectUnknownFlags(rawArgs, knownFlags, flagsWithValue) {
   return unknownFlags;
 }
 
-export function parseArgs(argv = process.argv) {
-  const args = argv.slice(2);
+export function parseArgs(
+  argv = process.argv,
+  runtime = { stdinIsTTY: process.stdin.isTTY, stdoutIsTTY: process.stdout.isTTY }
+) {
+  const args = normalizeCliArgs(argv.slice(2));
   const rawArgs = [...args];
 
   const wantsVersion = args.includes('--version') || args.includes('-v');
-  const wantsHelp = args.includes('--help') || args.includes('-h');
+  const wantsHelp = args.includes('--help') || args.includes('-h') || shouldDefaultToHelp(args, runtime);
   const wantsCache = args.includes('--cache');
   const wantsClean = args.includes('--clean');
   const wantsStatus = args.includes('--status');
@@ -132,14 +222,16 @@ export function parseArgs(argv = process.argv) {
     '--tail',
     '--no-follow',
     '--start',
+    '--register',
     '--stop',
     '--workspace',
+    '--fix',
     '--version',
     '-v',
     '--help',
     '-h',
   ]);
-  const flagsWithValue = new Set(['--tail', '--workspace', '--start', '--register']);
+  const flagsWithValue = FLAG_ARGS_WITH_VALUES;
   const unknownFlags = collectUnknownFlags(rawArgs, knownFlags, flagsWithValue);
 
   return {
@@ -164,3 +256,4 @@ export function parseArgs(argv = process.argv) {
     unknownFlags,
   };
 }
+

package/lib/config.js

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

package/lib/constants.js

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