@wonderwhy-er/desktop-commander 0.2.42 → 0.2.44

package/dist/terminal-manager.js

@@ -32,6 +32,17 @@ function getRepairedPathExt() {
     }
     return current;
 }
+/**
+ * Output buffering caps. Without a cap, a process emitting enough output makes
+ * string concatenation throw "RangeError: Invalid string length" at V8's max
+ * string size (~536M chars) inside a stdout 'data' handler — an uncaught
+ * exception that kills the whole server (index.ts exits on uncaughtException).
+ * The cap also bounds the join() cost in snapshot reads and the periodic
+ * process-state scan, both of which are O(total output).
+ */
+export const MAX_BUFFERED_OUTPUT_CHARS = 50 * 1024 * 1024; // per session; oldest lines evicted first
+const MAX_LINE_CHARS = 1024 * 1024; // force-split longer lines so eviction can work
+const MAX_WAIT_OUTPUT_CHARS = 2 * 1024 * 1024; // start_process wait buffer (prompt/state detection)
 /**
  * Get the appropriate spawn configuration for a given shell
  * This handles login shell flags for different shell types
@@ -207,7 +218,10 @@ export class TerminalManager {
             outputLines: [], // Line-based buffer
             lastReadIndex: 0, // Track where "new" output starts
             isBlocked: false,
-            startTime: new Date()
+            startTime: new Date(),
+            bufferedChars: 0,
+            evictedLines: 0,
+            evictedChars: 0
         };
         this.sessions.set(childProcess.pid, session);
         // Timing telemetry
@@ -249,7 +263,14 @@ export class TerminalManager {
                 if (!firstOutputTime)
                     firstOutputTime = now;
                 lastOutputTime = now;
-                output += text;
+                // `output` only feeds the wait-phase result and prompt/state detection,
+                // so stop growing it once resolved and keep only a bounded tail.
+                if (!resolved) {
+                    output += text;
+                    if (output.length > MAX_WAIT_OUTPUT_CHARS) {
+                        output = output.slice(-Math.floor(MAX_WAIT_OUTPUT_CHARS / 2));
+                    }
+                }
                 // Append to line-based buffer
                 this.appendToLineBuffer(session, text);
                 // Record output event if collecting timing
@@ -282,7 +303,12 @@ export class TerminalManager {
                 if (!firstOutputTime)
                     firstOutputTime = now;
                 lastOutputTime = now;
-                output += text;
+                if (!resolved) {
+                    output += text;
+                    if (output.length > MAX_WAIT_OUTPUT_CHARS) {
+                        output = output.slice(-Math.floor(MAX_WAIT_OUTPUT_CHARS / 2));
+                    }
+                }
                 // Append to line-based buffer
                 this.appendToLineBuffer(session, text);
                 // Record output event if collecting timing
@@ -329,7 +355,9 @@ export class TerminalManager {
                         outputLines: [...session.outputLines], // Copy line buffer
                         exitCode: code,
                         startTime: session.startTime,
-                        endTime: new Date()
+                        endTime: new Date(),
+                        evictedLines: session.evictedLines,
+                        evictedChars: session.evictedChars
                     });
                     // Keep only last 100 completed sessions
                     if (this.completedSessions.size > 100) {
@@ -373,6 +401,32 @@ export class TerminalManager {
                 session.outputLines.push(line);
             }
         }
+        // Appended text contributes exactly its length to the joined buffer
+        // (its newlines become the join separators).
+        session.bufferedChars += text.length;
+        // A process printing without newlines grows a single line forever, which
+        // eviction can't bound — force-split so no line exceeds MAX_LINE_CHARS.
+        // Each inserted break adds one separator to the joined length.
+        let lastIndex = session.outputLines.length - 1;
+        while (session.outputLines[lastIndex].length > MAX_LINE_CHARS) {
+            const overlong = session.outputLines[lastIndex];
+            session.outputLines[lastIndex] = overlong.slice(0, MAX_LINE_CHARS);
+            session.outputLines.push(overlong.slice(MAX_LINE_CHARS));
+            session.bufferedChars += 1;
+            lastIndex++;
+        }
+        // Enforce the per-session cap by evicting the oldest lines. Keeps the
+        // buffer far below V8's max string length so concatenation and join()
+        // can never throw "Invalid string length" and kill the server.
+        while (session.bufferedChars > MAX_BUFFERED_OUTPUT_CHARS && session.outputLines.length > 1) {
+            const dropped = session.outputLines.shift();
+            const droppedJoinedChars = dropped.length + 1; // +1 for its join separator
+            session.bufferedChars -= droppedJoinedChars;
+            session.evictedChars += droppedJoinedChars;
+            session.evictedLines++;
+            if (session.lastReadIndex > 0)
+                session.lastReadIndex--;
+        }
     }
     /**
      * Read process output with pagination (like file reading)
@@ -385,15 +439,19 @@ export class TerminalManager {
         // First check active sessions
         const session = this.sessions.get(pid);
         if (session) {
-            return this.readFromLineBuffer(session.outputLines, offset, length, session.lastReadIndex, (newIndex) => { session.lastReadIndex = newIndex; }, false, undefined);
+            const result = this.readFromLineBuffer(session.outputLines, offset, length, session.lastReadIndex, (newIndex) => { session.lastReadIndex = newIndex; }, false, undefined);
+            result.evictedLines = session.evictedLines;
+            return result;
         }
         // Then check completed sessions
         const completedSession = this.completedSessions.get(pid);
         if (completedSession) {
             const runtimeMs = completedSession.endTime.getTime() - completedSession.startTime.getTime();
-            return this.readFromLineBuffer(completedSession.outputLines, offset, length, 0, // Completed sessions don't track read position
+            const result = this.readFromLineBuffer(completedSession.outputLines, offset, length, 0, // Completed sessions don't track read position
             () => { }, // No-op for completed sessions
             true, completedSession.exitCode, runtimeMs);
+            result.evictedLines = completedSession.evictedLines;
+            return result;
         }
         return null;
     }
@@ -491,8 +549,11 @@ export class TerminalManager {
         if (session) {
             const fullOutput = session.outputLines.join('\n');
             return {
-                totalChars: fullOutput.length,
-                lineCount: session.outputLines.length
+                // Absolute since process start (includes evicted output), so the
+                // offset stays valid even if the cap evicts lines between
+                // snapshot and read.
+                totalChars: session.evictedChars + fullOutput.length,
+                lineCount: session.evictedLines + session.outputLines.length
             };
         }
         return null;
@@ -506,23 +567,28 @@ export class TerminalManager {
         // Check active session first
         const session = this.sessions.get(pid);
         if (session) {
-            const fullOutput = session.outputLines.join('\n');
-            if (fullOutput.length <= snapshot.totalChars) {
-                return ''; // No new output
-            }
-            return fullOutput.substring(snapshot.totalChars);
+            return TerminalManager.outputSinceSnapshot(session.outputLines, session.evictedChars, snapshot.totalChars);
         }
         // Fallback to completed sessions - process may have finished between snapshot and poll
         const completedSession = this.completedSessions.get(pid);
         if (completedSession) {
-            const fullOutput = completedSession.outputLines.join('\n');
-            if (fullOutput.length <= snapshot.totalChars) {
-                return ''; // No new output
-            }
-            return fullOutput.substring(snapshot.totalChars);
+            return TerminalManager.outputSinceSnapshot(completedSession.outputLines, completedSession.evictedChars, snapshot.totalChars);
         }
         return null;
     }
+    /**
+     * New output since a snapshot, in absolute (since process start) offsets.
+     * If eviction dropped part of the unseen output, returns what the buffer
+     * still holds — the oldest unseen chars are lost to the cap.
+     */
+    static outputSinceSnapshot(outputLines, evictedChars, snapshotTotalChars) {
+        const fullOutput = outputLines.join('\n');
+        const newChars = evictedChars + fullOutput.length - snapshotTotalChars;
+        if (newChars <= 0) {
+            return ''; // No new output
+        }
+        return fullOutput.substring(Math.max(0, fullOutput.length - newChars));
+    }
     /**
    * Get a session by PID
    * @param pid Process ID

package/dist/tools/edit.d.ts

@@ -19,7 +19,7 @@ interface SearchReplace {
     search: string;
     replace: string;
 }
-export declare function performSearchReplace(filePath: string, block: SearchReplace, expectedReplacements?: number): Promise<ServerResult>;
+export declare function performSearchReplace(filePath: string, block: SearchReplace, expectedReplacements?: number, origin?: 'ui' | 'llm'): Promise<ServerResult>;
 /**
  * Handle edit_block command
  *

package/dist/tools/edit.js

@@ -15,7 +15,7 @@
  * 3. Unify the editRange() signature to handle both text search/replace and structured edits
  */
 import { getDefaultEditorMetadata, writeFile, readFileInternal, validatePath } from './filesystem.js';
-import { recursiveFuzzyIndexOf, getSimilarityRatio } from './fuzzySearch.js';
+import { runFuzzySearchInWorker, getSimilarityRatio } from './fuzzySearch.js';
 import { capture } from '../utils/capture.js';
 import { createErrorResponse } from '../error-handlers.js';
 import { EditBlockArgsSchema } from "./schemas.js";
@@ -82,7 +82,7 @@ function getCharacterCodeData(expected, actual) {
         diffLength: fullDiff.length
     };
 }
-export async function performSearchReplace(filePath, block, expectedReplacements = 1) {
+export async function performSearchReplace(filePath, block, expectedReplacements = 1, origin) {
     // Get file extension for telemetry using path module
     const fileExtension = path.extname(filePath).toLowerCase();
     // Capture file extension and string sizes in telemetry without capturing the file path
@@ -176,13 +176,18 @@ RECOMMENDATION: For large search/replace operations, consider breaking them into
                     type: "text",
                     text: `${statusLine}${previewContent}`
                 }],
-            structuredContent: {
-                fileName: path.basename(resolvedEditPath),
-                filePath: resolvedEditPath,
-                fileType: resolvePreviewFileType(resolvedEditPath),
-                sourceTool: 'edit_block',
-                ...await getDefaultEditorMetadata(resolvedEditPath),
-            },
+            // structuredContent only travels on widget-initiated calls: it is the
+            // widget's save-success signal (assertSuccessfulEditBlockResult) and
+            // metadata source. LLM-facing responses don't need it — nothing there
+            // consumes it, and the widget re-reads by path instead.
+            ...(origin === 'ui' ? {
+                structuredContent: {
+                    fileName: path.basename(resolvedEditPath),
+                    filePath: resolvedEditPath,
+                    fileType: resolvePreviewFileType(resolvedEditPath),
+                    ...await getDefaultEditorMetadata(resolvedEditPath),
+                },
+            } : {}),
         };
     }
     // If exact match found but count doesn't match expected, inform the user
@@ -202,8 +207,9 @@ RECOMMENDATION: For large search/replace operations, consider breaking them into
     if (count === 0) {
         // Track fuzzy search time
         const startTime = performance.now();
-        // Perform fuzzy search
-        const fuzzyResult = recursiveFuzzyIndexOf(content, block.search);
+        // Perform fuzzy search in a worker thread so the main event loop stays
+        // responsive to pings and parallel tool calls during the scan
+        const fuzzyResult = await runFuzzySearchInWorker(content, block.search);
         const similarity = getSimilarityRatio(block.search, fuzzyResult.value);
         // Calculate execution time in milliseconds
         const executionTime = performance.now() - startTime;
@@ -366,13 +372,14 @@ export async function handleEditBlock(args) {
                             type: "text",
                             text: `Successfully updated range ${parsed.range} in ${parsed.file_path}`
                         }],
-                    structuredContent: {
-                        fileName: path.basename(resolvedRangePath),
-                        filePath: resolvedRangePath,
-                        fileType: resolvePreviewFileType(resolvedRangePath),
-                        sourceTool: 'edit_block',
-                        ...await getDefaultEditorMetadata(resolvedRangePath),
-                    },
+                    ...(parsed.origin === 'ui' ? {
+                        structuredContent: {
+                            fileName: path.basename(resolvedRangePath),
+                            filePath: resolvedRangePath,
+                            fileType: resolvePreviewFileType(resolvedRangePath),
+                            ...await getDefaultEditorMetadata(resolvedRangePath),
+                        },
+                    } : {}),
                 };
             }
             catch (error) {
@@ -403,13 +410,14 @@ export async function handleEditBlock(args) {
                             type: "text",
                             text: `Successfully applied ${result.editsApplied} edit(s) to ${parsed.file_path}`
                         }],
-                    structuredContent: {
-                        fileName: path.basename(resolvedEditRangePath),
-                        filePath: resolvedEditRangePath,
-                        fileType: resolvePreviewFileType(resolvedEditRangePath),
-                        sourceTool: 'edit_block',
-                        ...await getDefaultEditorMetadata(resolvedEditRangePath),
-                    },
+                    ...(parsed.origin === 'ui' ? {
+                        structuredContent: {
+                            fileName: path.basename(resolvedEditRangePath),
+                            filePath: resolvedEditRangePath,
+                            fileType: resolvePreviewFileType(resolvedEditRangePath),
+                            ...await getDefaultEditorMetadata(resolvedEditRangePath),
+                        },
+                    } : {}),
                 };
             }
             const errorMsg = result.errors?.map(e => e.error).join('; ') || 'Unknown error';
@@ -423,5 +431,5 @@ export async function handleEditBlock(args) {
     return performSearchReplace(parsed.file_path, {
         search: parsed.old_string,
         replace: parsed.new_string
-    }, parsed.expected_replacements);
+    }, parsed.expected_replacements, parsed.origin);
 }

package/dist/tools/filesystem.d.ts

@@ -1,5 +1,6 @@
 import type { ReadOptions, FileResult, PdfPageItem } from '../utils/files/base.js';
 import { PdfOperations, PdfMetadata } from './pdf/index.js';
+export declare const READ_OPERATION_TIMEOUT_MS: number;
 /**
  * Validates a path to ensure it can be accessed or created.
  * For existing paths, returns the real path (resolving symlinks).

package/dist/tools/filesystem.js

@@ -5,7 +5,7 @@ import fetch from 'cross-fetch';
 import { execFile } from 'child_process';
 import { promisify } from 'util';
 import { capture } from '../utils/capture.js';
-import { withTimeout } from '../utils/withTimeout.js';
+import { withTimeout, runWithAbortableTimeout } from '../utils/withTimeout.js';
 import { configManager } from '../config-manager.js';
 import { getFileHandler, TextFileHandler } from '../utils/files/index.js';
 import { isPdfFile } from "./mime-types.js";
@@ -16,6 +16,13 @@ const FILE_OPERATION_TIMEOUTS = {
     URL_FETCH: 30000, // 30 seconds
     FILE_READ: 30000, // 30 seconds
 };
+// Cap file read operations at 3 minutes. The MCP client's hard per-call limit
+// is ~4 minutes; timing out at 3m lets us abort the underlying fs op and return
+// a useful error (e.g. the cloud-storage guidance in buildPermissionError)
+// BEFORE the client gives up with an opaque "No result received after 4
+// minutes". Paired with runWithAbortableTimeout so the read is actually
+// cancelled (fd/thread released), not just abandoned.
+export const READ_OPERATION_TIMEOUT_MS = 3 * 60 * 1000; // 3 minutes
 const FILE_SIZE_LIMITS = {
     LINE_COUNT_LIMIT: 10 * 1024 * 1024, // 10MB for line counting
 };
@@ -426,8 +433,9 @@ export async function readFileFromDisk(filePath, options) {
         capture('server_read_file_error', { error: errorMessage, fileExtension: fileExtension });
         // If we can't stat the file, continue anyway and let the read operation handle errors
     }
-    // Use withTimeout to handle potential hangs
-    const readOperation = async () => {
+    // Read under an abortable timeout so a hung/stalled read is cancelled
+    // (fd/thread freed) rather than leaked until the OS call returns.
+    const readOperation = async (signal) => {
         // Get appropriate handler for this file type (async - includes binary detection)
         const handler = await getFileHandler(validPath);
         // Use handler to read the file
@@ -436,7 +444,8 @@ export async function readFileFromDisk(filePath, options) {
             length,
             sheet,
             range,
-            includeStatusMessage: true
+            includeStatusMessage: true,
+            signal
         });
         // Return with content as string
         // For images: content is already base64-encoded string from handler
@@ -458,18 +467,17 @@ export async function readFileFromDisk(filePath, options) {
             metadata: result.metadata
         };
     };
-    // Execute with timeout
+    // Execute with a 3-minute, cancellable timeout
     let result;
     try {
-        result = await withTimeout(readOperation(), FILE_OPERATION_TIMEOUTS.FILE_READ, `Read file operation for ${filePath}`, null);
+        result = await runWithAbortableTimeout((signal) => readOperation(signal), READ_OPERATION_TIMEOUT_MS, `Read file operation for ${filePath}`);
     }
     catch (error) {
         const err = error;
-        // withTimeout rejects with a plain string "__ERROR__: ... timed out after N seconds"
-        // when defaultValue is null — it has no .code property, so check for that too.
-        const isWithTimeoutString = typeof error === 'string' && error.startsWith('__ERROR__:');
-        if (isWithTimeoutString || err.code === 'EPERM' || err.code === 'EACCES' || err.code === 'ETIMEDOUT') {
-            throw buildPermissionError(filePath, isWithTimeoutString ? 'ETIMEDOUT' : err.code);
+        // runWithAbortableTimeout rejects with an Error whose .code is 'ETIMEDOUT'
+        // on timeout; fs rejects with EPERM/EACCES. Map all to the guidance error.
+        if (err.code === 'EPERM' || err.code === 'EACCES' || err.code === 'ETIMEDOUT') {
+            throw buildPermissionError(filePath, err.code);
         }
         throw error;
     }
@@ -515,8 +523,10 @@ export async function readFileInternal(filePath, offset = 0, length) {
     // IMPORTANT: For internal operations (especially edit operations), we must
     // preserve exact file content including original line endings.
     // We cannot use readline-based reading as it strips line endings.
-    // Read entire file content preserving line endings
-    const content = await fs.readFile(validPath, 'utf8');
+    // Read entire file content preserving line endings, under a 3-minute,
+    // cancellable timeout so an edit on a stalled/cloud path can't hang forever
+    // (previously this read had no timeout at all).
+    const content = await runWithAbortableTimeout((signal) => fs.readFile(validPath, { encoding: 'utf8', signal }), READ_OPERATION_TIMEOUT_MS, `Internal read for ${filePath}`);
     // If we need to apply offset/length, do it while preserving line endings
     if (offset === 0 && length >= Number.MAX_SAFE_INTEGER) {
         // Most common case for edit operations: read entire file

package/dist/tools/fuzzySearch.d.ts

@@ -1,22 +1,12 @@
+import type { FuzzyMatch } from './fuzzySearchCore.js';
+export { recursiveFuzzyIndexOf, getSimilarityRatio } from './fuzzySearchCore.js';
+/** Abort fuzzy search in the worker after this many ms to avoid unbounded CPU burn. */
+export declare const FUZZY_SEARCH_TIMEOUT_MS = 30000;
 /**
- * Recursively finds the closest match to a query string within text using fuzzy matching
- * @param text The text to search within
- * @param query The query string to find
- * @param start Start index in the text (default: 0)
- * @param end End index in the text (default: text.length)
- * @param parentDistance Best distance found so far (default: Infinity)
- * @returns Object with start and end indices, matched value, and Levenshtein distance
+ * Runs the fuzzy search in a Worker thread so the main MCP event loop stays
+ * responsive to pings and other tool calls during heavy scans. Rejects if the
+ * scan exceeds timeoutMs, terminating the worker so it doesn't linger in the
+ * background. Search metrics come back with the result and are captured here,
+ * on the main thread, where the client identity is initialized.
  */
-export declare function recursiveFuzzyIndexOf(text: string, query: string, start?: number, end?: number | null, parentDistance?: number, depth?: number): {
-    start: number;
-    end: number;
-    value: string;
-    distance: number;
-};
-/**
- * Calculates the similarity ratio between two strings
- * @param a First string
- * @param b Second string
- * @returns Similarity ratio (0-1)
- */
-export declare function getSimilarityRatio(a: string, b: string): number;
+export declare function runFuzzySearchInWorker(text: string, query: string, timeoutMs?: number): Promise<FuzzyMatch>;

package/dist/tools/fuzzySearch.js

@@ -1,113 +1,74 @@
-import { distance } from 'fastest-levenshtein';
 import { capture } from '../utils/capture.js';
+import { Worker } from 'worker_threads';
+// Re-export so existing callers keep importing from this module.
+export { recursiveFuzzyIndexOf, getSimilarityRatio } from './fuzzySearchCore.js';
+/** Abort fuzzy search in the worker after this many ms to avoid unbounded CPU burn. */
+export const FUZZY_SEARCH_TIMEOUT_MS = 30000;
 /**
- * Recursively finds the closest match to a query string within text using fuzzy matching
- * @param text The text to search within
- * @param query The query string to find
- * @param start Start index in the text (default: 0)
- * @param end End index in the text (default: text.length)
- * @param parentDistance Best distance found so far (default: Infinity)
- * @returns Object with start and end indices, matched value, and Levenshtein distance
+ * Inline worker entry: imports the dependency-free core module (passed as
+ * moduleUrl) and runs the search off the main thread. The core module is
+ * deliberately a leaf — importing this module (or anything app-level) from the
+ * worker would boot the whole server per search. Kept as an eval'd snippet so
+ * the worker needs no separate file to ship alongside the compiled output.
  */
-export function recursiveFuzzyIndexOf(text, query, start = 0, end = null, parentDistance = Infinity, depth = 0) {
-    // For debugging and performance tracking purposes
-    if (depth === 0) {
-        const startTime = performance.now();
-        const result = recursiveFuzzyIndexOf(text, query, start, end, parentDistance, depth + 1);
-        const executionTime = performance.now() - startTime;
-        // Capture detailed metrics for the recursive search for in-depth analysis
-        capture('fuzzy_search_recursive_metrics', {
-            execution_time_ms: executionTime,
-            text_length: text.length,
-            query_length: query.length,
-            result_distance: result.distance
-        });
-        return result;
-    }
-    if (end === null)
-        end = text.length;
-    // For small text segments, use iterative approach
-    if (end - start <= 2 * query.length) {
-        return iterativeReduction(text, query, start, end, parentDistance);
-    }
-    let midPoint = start + Math.floor((end - start) / 2);
-    let leftEnd = Math.min(end, midPoint + query.length); // Include query length to cover overlaps
-    let rightStart = Math.max(start, midPoint - query.length); // Include query length to cover overlaps
-    // Calculate distance for current segments
-    let leftDistance = distance(text.substring(start, leftEnd), query);
-    let rightDistance = distance(text.substring(rightStart, end), query);
-    let bestDistance = Math.min(leftDistance, parentDistance, rightDistance);
-    // If parent distance is already the best, use iterative approach
-    if (parentDistance === bestDistance) {
-        return iterativeReduction(text, query, start, end, parentDistance);
-    }
-    // Recursively search the better half
-    if (leftDistance < rightDistance) {
-        return recursiveFuzzyIndexOf(text, query, start, leftEnd, bestDistance, depth + 1);
-    }
-    else {
-        return recursiveFuzzyIndexOf(text, query, rightStart, end, bestDistance, depth + 1);
-    }
-}
+const WORKER_CODE = `
+const { workerData, parentPort } = require('worker_threads');
+import(workerData.moduleUrl)
+    .then((m) => {
+        parentPort.postMessage({ ok: true, ...m.runFuzzySearch(workerData.text, workerData.query) });
+    })
+    .catch((err) => {
+        parentPort.postMessage({ ok: false, error: String(err && err.stack || err) });
+    });
+`;
+const CORE_MODULE_URL = new URL('./fuzzySearchCore.js', import.meta.url).href;
 /**
- * Iteratively refines the best match by reducing the search area
- * @param text The text to search within
- * @param query The query string to find
- * @param start Start index in the text
- * @param end End index in the text
- * @param parentDistance Best distance found so far
- * @returns Object with start and end indices, matched value, and Levenshtein distance
+ * Runs the fuzzy search in a Worker thread so the main MCP event loop stays
+ * responsive to pings and other tool calls during heavy scans. Rejects if the
+ * scan exceeds timeoutMs, terminating the worker so it doesn't linger in the
+ * background. Search metrics come back with the result and are captured here,
+ * on the main thread, where the client identity is initialized.
  */
-function iterativeReduction(text, query, start, end, parentDistance) {
-    const startTime = performance.now();
-    let iterations = 0;
-    let bestDistance = parentDistance;
-    let bestStart = start;
-    let bestEnd = end;
-    // Improve start position
-    let nextDistance = distance(text.substring(bestStart + 1, bestEnd), query);
-    while (nextDistance < bestDistance) {
-        bestDistance = nextDistance;
-        bestStart++;
-        const smallerString = text.substring(bestStart + 1, bestEnd);
-        nextDistance = distance(smallerString, query);
-        iterations++;
-    }
-    // Improve end position
-    nextDistance = distance(text.substring(bestStart, bestEnd - 1), query);
-    while (nextDistance < bestDistance) {
-        bestDistance = nextDistance;
-        bestEnd--;
-        const smallerString = text.substring(bestStart, bestEnd - 1);
-        nextDistance = distance(smallerString, query);
-        iterations++;
-    }
-    const executionTime = performance.now() - startTime;
-    // Capture metrics for the iterative refinement phase
-    capture('fuzzy_search_iterative_metrics', {
-        execution_time_ms: executionTime,
-        iterations: iterations,
-        segment_length: end - start,
-        query_length: query.length,
-        final_distance: bestDistance
+export function runFuzzySearchInWorker(text, query, timeoutMs = FUZZY_SEARCH_TIMEOUT_MS) {
+    return new Promise((resolve, reject) => {
+        const worker = new Worker(WORKER_CODE, { eval: true, workerData: { moduleUrl: CORE_MODULE_URL, text, query } });
+        // Never let a scan keep the server process alive during shutdown.
+        worker.unref();
+        const timer = setTimeout(() => {
+            worker.terminate();
+            reject(new Error(`Fuzzy search timed out after ${timeoutMs}ms`));
+        }, timeoutMs);
+        timer.unref();
+        worker.on('message', (msg) => {
+            clearTimeout(timer);
+            if (msg.ok) {
+                captureFuzzySearchMetrics(msg.metrics);
+                resolve(msg.result);
+            }
+            else {
+                reject(new Error(`Fuzzy search worker failed: ${msg.error}`));
+            }
+            // Don't let the worker wind down on its own; the answer is already
+            // here, and a lingering worker holds its copy of the file text.
+            // The promise is settled, so the exit-code rejection below is a no-op.
+            worker.terminate();
+        });
+        worker.on('error', (err) => {
+            clearTimeout(timer);
+            reject(err);
+        });
+        worker.on('exit', (code) => {
+            clearTimeout(timer);
+            if (code !== 0) {
+                reject(new Error(`Fuzzy search worker exited with code ${code}`));
+            }
+        });
     });
-    return {
-        start: bestStart,
-        end: bestEnd,
-        value: text.substring(bestStart, bestEnd),
-        distance: bestDistance
-    };
 }
-/**
- * Calculates the similarity ratio between two strings
- * @param a First string
- * @param b Second string
- * @returns Similarity ratio (0-1)
- */
-export function getSimilarityRatio(a, b) {
-    const maxLength = Math.max(a.length, b.length);
-    if (maxLength === 0)
-        return 1; // Both strings are empty
-    const levenshteinDistance = distance(a, b);
-    return 1 - (levenshteinDistance / maxLength);
+/** Same telemetry events the search used to emit inline, now sent from the main thread. */
+function captureFuzzySearchMetrics(metrics) {
+    capture('fuzzy_search_recursive_metrics', metrics.recursive);
+    if (metrics.iterative) {
+        capture('fuzzy_search_iterative_metrics', metrics.iterative);
+    }
 }