@wonderwhy-er/desktop-commander 0.2.43 → 0.2.44

package/dist/ui/file-preview/src/app.js

@@ -19,7 +19,6 @@ import { attachPanelActions } from './panel-actions.js';
 import { extractRenderPayload, extractToolText, getFileExtensionForAnalytics, isLikelyUrl, isPreviewStructuredContent } from './payload-utils.js';
 let isExpanded = false;
 let hideSummaryRow = false;
-let previewShownFired = false;
 let onRender;
 let trackUiEvent;
 let conflictDialogController;
@@ -128,43 +127,113 @@ const markdownController = createMarkdownController({
         options.onCancel?.();
     },
 });
+// Only read_file's own parameters may ride along on a re-read. Forwarding a
+// different tool's args (e.g. edit_block's old_string) makes the server prepend
+// an "unsupported params" warning that would pollute the pulled content.
+const READ_ARG_KEYS = ['path', 'offset', 'length', 'sheet', 'range', 'isUrl'];
+function pickReadArgs(args) {
+    if (!args || typeof args !== 'object') {
+        return undefined;
+    }
+    const src = args;
+    // edit_block calls the file "file_path"; read_file/write_file call it "path".
+    const path = typeof src.path === 'string'
+        ? src.path
+        : typeof src.file_path === 'string'
+            ? src.file_path
+            : undefined;
+    if (!path) {
+        return undefined;
+    }
+    const out = { path };
+    for (const key of READ_ARG_KEYS) {
+        if (key !== 'path' && src[key] !== undefined) {
+            out[key] = src[key];
+        }
+    }
+    return out;
+}
+// The host doesn't send the tool name with tool-input, so infer mutations from
+// their arg shape: write_file carries `content`; edit_block `old_string`/
+// `new_string`. Drives two things: timing (a mutation's tool-input arrives
+// BEFORE the file changes, so those pull at tool-result time instead of input
+// time) and telemetry (the pulled payload's sourceTool is re-stamped with the
+// originating tool, since the pull itself is always a read_file).
+function inferMutationTool(args) {
+    if (!args || typeof args !== 'object') {
+        return undefined;
+    }
+    const src = args;
+    if (src.old_string !== undefined || src.new_string !== undefined) {
+        return 'edit_block';
+    }
+    if (src.content !== undefined) {
+        return 'write_file';
+    }
+    return undefined;
+}
+// Bound the RPC read so a stalled host response resolves to onFail instead of
+// hanging. Kept under the loading watchdog (PREVIEW_WATCHDOG_MS) so the pull
+// gets its chance to fail before the failure row appears.
+const PULL_TIMEOUT_MS = 8000;
+// One in-flight pull per path — the input-time pull and a tool-result-triggered
+// pull for the same call would otherwise read the file twice.
+let pullInFlightPath;
 /**
- * Check if a payload needs its file content to be read.
- * Tool results from edit_block/write_file include structuredContent but
- * their text is a success message, not file content. Detect this by
- * checking for the absence of the read status line that read_file always includes.
- * URL payloads are fetched remotely by read_file(isUrl:true); we can't
- * re-fetch them from here (no isUrl flag on the refresh path), so skip.
+ * The widget's render path: pull content + metadata over the RPC channel
+ * (`app.callServerTool` with origin:'ui'). The notification channel is not used
+ * for rendering — the host may strip structuredContent from it or swallow it
+ * entirely (images). `args` reproduces the original read exactly
+ * (offset/length/sheet/range/isUrl) so partial reads stay faithful.
  */
-function needsContentRead(payload) {
-    if (payload.fileType === 'directory' || payload.fileType === 'image' || payload.fileType === 'unsupported') {
-        return false;
+async function pullPayloadByArgs(args, onReady, onFail) {
+    const filePath = typeof args.path === 'string' ? args.path : undefined;
+    if (!filePath) {
+        onFail();
+        return;
     }
-    if (/^https?:\/\//i.test(payload.filePath)) {
-        return false;
+    if (pullInFlightPath === filePath) {
+        return;
     }
-    return !parseReadRange(payload.content);
-}
-async function readAndResolvePayload(payload, onReady) {
+    pullInFlightPath = filePath;
     try {
-        const freshPayload = await markdownController.readPayload(payload.filePath);
-        if (freshPayload) {
-            onReady({
-                ...freshPayload,
-                sourceTool: payload.sourceTool ?? freshPayload.sourceTool,
-            });
-            if (freshPayload.fileType === 'markdown') {
-                void markdownController.refreshFromDisk(freshPayload);
-            }
+        // The host can hold the RPC response indefinitely (e.g. it preempts
+        // delivery to inline-render an image), so callServerTool would await
+        // forever with no throw. Race a timeout so the pull settles either way.
+        const raw = await Promise.race([
+            callToolIfReady('read_file', { ...args, origin: 'ui' }),
+            new Promise((_resolve, reject) => {
+                setTimeout(() => reject(new Error(`RPC read_file did not respond within ${PULL_TIMEOUT_MS}ms`)), PULL_TIMEOUT_MS);
+            }),
+        ]);
+        const payload = extractRenderPayload(raw);
+        if (payload) {
+            onReady(payload);
             return;
         }
     }
     catch {
-        // Fall through to original payload.
+        // Timed out or rejected — fall through to the caller's fallback.
+    }
+    finally {
+        pullInFlightPath = undefined;
+    }
+    onFail();
+}
+// If a loading state hasn't resolved into a real render within this window, the
+// host most likely never delivered the tool result / RPC response (e.g. it
+// preempted delivery to inline-render an image). Rather than sit on "Preparing
+// preview…" forever, we surface a failure row.
+const PREVIEW_WATCHDOG_MS = 10000;
+let previewWatchdogId;
+function clearPreviewWatchdog() {
+    if (previewWatchdogId !== undefined) {
+        clearTimeout(previewWatchdogId);
+        previewWatchdogId = undefined;
     }
-    onReady(payload);
 }
 function renderStatusState(container, message) {
+    clearPreviewWatchdog();
     container.innerHTML = `
       <main class="shell">
         ${renderCompactRow({ label: message, variant: 'status', interactive: false })}
@@ -179,8 +248,16 @@ function renderLoadingState(container) {
       </main>
     `;
     document.body.classList.add('dc-ready');
+    // Fall back to a failure row if nothing renders in time. Any successful
+    // render (renderApp) or explicit status clears this first.
+    clearPreviewWatchdog();
+    previewWatchdogId = setTimeout(() => {
+        previewWatchdogId = undefined;
+        renderStatusState(container, 'Unable to generate preview in this environment.');
+    }, PREVIEW_WATCHDOG_MS);
 }
 export function renderApp(container, payload, htmlMode = 'rendered', expandedState = false) {
+    clearPreviewWatchdog();
     isExpanded = expandedState;
     currentHtmlMode = htmlMode;
     shellController?.dispose();
@@ -314,13 +391,6 @@ export function renderApp(container, payload, htmlMode = 'rendered', expandedSta
         onRender,
     });
     onRender?.();
-    if (!previewShownFired) {
-        previewShownFired = true;
-        trackUiEvent?.('preview_shown', {
-            file_type: payload.fileType,
-            file_extension: fileExtension,
-        });
-    }
 }
 export function bootstrapApp() {
     const container = document.getElementById('app');
@@ -376,6 +446,14 @@ export function bootstrapApp() {
         renderApp(container, currentPayload, currentHtmlMode, isExpanded);
     };
     let pendingCachedPayload;
+    let lastToolInputArgs;
+    // The mutation tool that produced the current tool call, if any — stamped
+    // onto the pulled payload so telemetry attributes to write_file/edit_block
+    // rather than the read_file pull that rendered it.
+    let lastMutationTool;
+    // True once the current tool call has been rendered (via the input-time pull),
+    // so a late tool-result notification doesn't trigger a redundant second pull.
+    let renderedForCurrentInput = false;
     let initialStateResolved = false;
     const resolveInitialState = (payload, message) => {
         if (initialStateResolved) {
@@ -423,6 +501,13 @@ export function bootstrapApp() {
     });
     app.ontoolinput = (params) => {
         const requestedPath = typeof params.arguments?.path === 'string' ? params.arguments.path : undefined;
+        const readArgs = pickReadArgs(params.arguments);
+        lastMutationTool = inferMutationTool(params.arguments);
+        if (readArgs) {
+            // Retained so mutations (which pull at tool-result time) know what
+            // to re-read — faithfully reproducing offset/length/sheet/range.
+            lastToolInputArgs = readArgs;
+        }
         if (!initialStateResolved
             && pendingCachedPayload
             && requestedPath
@@ -434,38 +519,71 @@ export function bootstrapApp() {
         }
         renderLoadingState(container);
         onRender?.();
+        renderedForCurrentInput = false;
+        // All previews render from the widget's own origin:'ui' RPC read — the
+        // notification channel is unreliable (the host strips structuredContent,
+        // and for images swallows the tool-result entirely to inline-render).
+        // tool-input always fires and carries the path + read args, so pull here.
+        // Exception: mutations (write_file/edit_block) — their tool-input arrives
+        // before the file changes, so they pull at tool-result time instead.
+        if (readArgs && !lastMutationTool) {
+            void pullPayloadByArgs(readArgs, (p) => {
+                renderedForCurrentInput = true;
+                if (initialStateResolved) {
+                    renderAndSync(getEffectiveIncomingPayload(p));
+                }
+                else {
+                    resolveInitialState(getEffectiveIncomingPayload(p));
+                }
+            }, 
+            // Pull failed/timed out — the loading watchdog shows the failure row.
+            () => { });
+        }
     };
     app.ontoolresult = (result) => {
         pendingCachedPayload = undefined;
-        const payload = extractRenderPayload(result);
+        // Host-facing responses carry no structuredContent, so this notification
+        // only signals completion. Reads already rendered from their input-time
+        // pull; mutations (write_file/edit_block) pull now that the file changed.
+        if (renderedForCurrentInput) {
+            return;
+        }
         const message = extractToolText(result);
-        if (!initialStateResolved) {
-            if (payload) {
-                if (needsContentRead(payload)) {
-                    void readAndResolvePayload(payload, (p) => resolveInitialState(getEffectiveIncomingPayload(p)));
-                    return;
-                }
-                resolveInitialState(getEffectiveIncomingPayload(payload));
+        const isError = result?.isError === true;
+        const pullArgs = lastToolInputArgs
+            ?? (currentPayload?.filePath ? { path: currentPayload.filePath } : undefined);
+        const deliver = (pulled) => {
+            renderedForCurrentInput = true;
+            // The pull is always a read_file; re-stamp the originating mutation
+            // tool so telemetry attributes to write_file/edit_block.
+            const p = lastMutationTool ? { ...pulled, sourceTool: lastMutationTool } : pulled;
+            if (initialStateResolved) {
+                renderAndSync(getEffectiveIncomingPayload(p));
+            }
+            else {
+                resolveInitialState(getEffectiveIncomingPayload(p));
+            }
+        };
+        const renderMessageFallback = () => {
+            if (!message) {
                 return;
             }
-            if (message) {
+            if (!initialStateResolved) {
                 resolveInitialState(undefined, message);
             }
-            return;
-        }
-        if (payload) {
-            if (needsContentRead(payload)) {
-                renderLoadingState(container);
-                void readAndResolvePayload(payload, (p) => renderAndSync(getEffectiveIncomingPayload(p)));
-            }
             else {
-                renderAndSync(getEffectiveIncomingPayload(payload));
+                renderStatusState(container, message);
+                onRender?.();
             }
-        }
-        else if (message) {
-            renderStatusState(container, message);
+        };
+        // A failed tool call has nothing worth re-reading — show its message.
+        if (!isError && pullArgs) {
+            renderLoadingState(container);
             onRender?.();
+            void pullPayloadByArgs(pullArgs, deliver, renderMessageFallback);
+            return;
         }
+        renderMessageFallback();
     };
     app.ontoolcancelled = (params) => {
         resolveInitialState(undefined, params.reason ?? 'Tool was cancelled.');
@@ -484,6 +602,7 @@ export function bootstrapApp() {
         }
     };
     const teardown = () => {
+        clearPreviewWatchdog();
         shellController?.dispose();
         shellController = undefined;
         markdownController.disposeHandles();

package/dist/ui/file-preview/src/directory-controller.js

@@ -128,7 +128,7 @@ export function attachDirectoryHandlers(options) {
             const command = options.buildOpenInFolderCommand(openPath);
             if (command) {
                 try {
-                    await options.callTool?.('start_process', { command, timeout_ms: 12000 });
+                    await options.callTool?.('start_process', { command, timeout_ms: 12000, origin: 'ui' });
                 }
                 catch {
                     // Keep UI stable if opening folder fails.

package/dist/ui/file-preview/src/markdown/controller.js

@@ -388,6 +388,7 @@ export function createMarkdownController(dependencies) {
             maxResults: 20,
             earlyTermination: false,
             literalSearch: true,
+            origin: 'ui',
         });
         const text = extractToolText(result) ?? '';
         const filePaths = parseFileSearchResults(text);

package/dist/ui/file-preview/src/panel-actions.js

@@ -95,7 +95,7 @@ export function attachPanelActions(options) {
                     file_extension: fileExtension,
                 });
                 try {
-                    await options.callTool?.('start_process', { command, timeout_ms: 12000 });
+                    await options.callTool?.('start_process', { command, timeout_ms: 12000, origin: 'ui' });
                 }
                 catch {
                     // Keep UI stable if opening folder fails.
@@ -116,7 +116,7 @@ export function attachPanelActions(options) {
                     file_extension: fileExtension,
                 });
                 try {
-                    await options.callTool?.('start_process', { command, timeout_ms: 12000 });
+                    await options.callTool?.('start_process', { command, timeout_ms: 12000, origin: 'ui' });
                 }
                 catch {
                     // Keep UI stable if opening editor fails.

package/dist/ui/file-preview/src/payload-utils.js

@@ -41,11 +41,27 @@ export function extractToolText(value) {
     }
     return undefined;
 }
-function extractStructuredContentText(value) {
+// Join ALL non-empty text blocks, not just the first. Most reads return a
+// single text block, but PDF reads return a summary block followed by
+// per-page text blocks — taking only the first would drop the page text.
+function extractJoinedToolText(value) {
     if (!isObjectRecord(value)) {
         return undefined;
     }
-    return typeof value.content === 'string' ? value.content : undefined;
+    const content = value.content;
+    if (!Array.isArray(content)) {
+        return undefined;
+    }
+    const texts = [];
+    for (const item of content) {
+        if (isObjectRecord(item)
+            && item.type === 'text'
+            && typeof item.text === 'string'
+            && item.text.trim().length > 0) {
+            texts.push(item.text);
+        }
+    }
+    return texts.length > 0 ? texts.join('\n') : undefined;
 }
 export function extractRenderPayload(value) {
     if (!isObjectRecord(value)) {
@@ -58,11 +74,11 @@ export function extractRenderPayload(value) {
             : null;
     if (!meta)
         return undefined;
-    const text = extractStructuredContentText(value.structuredContent)
-        ?? extractToolText(value)
-        ?? extractToolText(value.structuredContent)
-        ?? '';
-    return buildRenderPayload(meta, text);
+    // Content always comes from the read output's content[] text blocks; the
+    // structuredContent alongside it is metadata-only. Images arrive as a base64
+    // text block too (origin:'ui' reads carry no image block, so the host won't
+    // inline-render and stall the RPC).
+    return buildRenderPayload(meta, extractJoinedToolText(value) ?? '');
 }
 export function assertSuccessfulEditBlockResult(result) {
     if (!isObjectRecord(result)) {

package/dist/utils/capture.d.ts

@@ -1,3 +1,5 @@
+export declare function runInUiOriginCallContext<T>(fn: () => T): T;
+export declare function isInsideUiOriginCall(): boolean;
 /**
  * Hard kill-switch for telemetry via environment variable.
  *

package/dist/utils/capture.js

@@ -1,7 +1,21 @@
 import { platform } from 'os';
 import * as https from 'https';
+import { AsyncLocalStorage } from 'async_hooks';
 import { configManager, isTelemetryDisabledValue } from '../config-manager.js';
 import { currentClient, currentCallIsRemote, currentRemoteClient } from '../server.js';
+// Execution context for tool calls fired programmatically by the widget UIs
+// (file preview, config editor), marked by args.origin === 'ui'. While code
+// runs inside this context, capture() drops every event, so UI refresh churn
+// (pull-by-path reads, in-preview saves, folder expansion, link search, ...)
+// produces zero telemetry. AsyncLocalStorage (rather than a module-level flag)
+// keeps attribution correct when a widget call interleaves with an agent call.
+const uiOriginCallContext = new AsyncLocalStorage();
+export function runInUiOriginCallContext(fn) {
+    return uiOriginCallContext.run(true, fn);
+}
+export function isInsideUiOriginCall() {
+    return uiOriginCallContext.getStore() === true;
+}
 let VERSION = 'unknown';
 try {
     const versionModule = await import('../version.js');
@@ -427,6 +441,11 @@ const postTelemetryPayload = async (endpoint, payload) => {
 // can be silently dropped. If we need delivery guarantees on short-lived paths,
 // expose an awaitable variant or flush-before-exit hook.
 export const capture = async (event, properties) => {
+    // Tool calls fired programmatically by the widget UIs must produce zero
+    // telemetry — drop every event raised while serving one.
+    if (isInsideUiOriginCall()) {
+        return;
+    }
     void (async () => {
         try {
             const eventProperties = await buildEventProperties(properties);

package/dist/utils/files/base.d.ts

@@ -69,6 +69,8 @@ export interface ReadOptions {
     range?: string;
     /** Whether to include status messages (default: true) */
     includeStatusMessage?: boolean;
+    /** Optional AbortSignal to cancel an in-flight read (frees fd/thread on timeout). */
+    signal?: AbortSignal;
 }
 /**
  * Result from reading a file

package/dist/utils/files/image.js

@@ -14,7 +14,7 @@ export class ImageFileHandler {
     }
     async read(path, options) {
         // Images are always read in full, ignoring offset and length
-        const buffer = await fs.readFile(path);
+        const buffer = await fs.readFile(path, { signal: options?.signal });
         const content = buffer.toString('base64');
         const mimeType = this.getMimeType(path);
         return {

package/dist/utils/files/text.js

@@ -43,7 +43,7 @@ export class TextFileHandler {
         const length = options?.length ?? 1000; // Default from config
         const includeStatusMessage = options?.includeStatusMessage ?? true;
         // Binary detection is done at factory level - just read as text
-        return this.readFileWithSmartPositioning(filePath, offset, length, 'text/plain', includeStatusMessage);
+        return this.readFileWithSmartPositioning(filePath, offset, length, 'text/plain', includeStatusMessage, options?.signal);
     }
     async write(path, content, mode = 'rewrite') {
         if (mode === 'append') {
@@ -100,11 +100,11 @@ export class TextFileHandler {
     /**
      * Get file line count (for files under size limit)
      */
-    async getFileLineCount(filePath) {
+    async getFileLineCount(filePath, signal) {
         try {
             const stats = await fs.stat(filePath);
             if (stats.size < FILE_SIZE_LIMITS.LINE_COUNT_LIMIT) {
-                const content = await fs.readFile(filePath, 'utf8');
+                const content = await fs.readFile(filePath, { encoding: 'utf8', signal });
                 return TextFileHandler.countLines(content);
             }
         }
@@ -179,32 +179,32 @@ export class TextFileHandler {
     /**
      * Read file with smart positioning for optimal performance
      */
-    async readFileWithSmartPositioning(filePath, offset, length, mimeType, includeStatusMessage = true) {
+    async readFileWithSmartPositioning(filePath, offset, length, mimeType, includeStatusMessage = true, signal) {
         const stats = await fs.stat(filePath);
         const fileSize = stats.size;
-        const totalLines = await this.getFileLineCount(filePath);
+        const totalLines = await this.getFileLineCount(filePath, signal);
         // For negative offsets (tail behavior), use reverse reading
         if (offset < 0) {
             const requestedLines = Math.abs(offset);
             if (fileSize > FILE_SIZE_LIMITS.LARGE_FILE_THRESHOLD &&
                 requestedLines <= READ_PERFORMANCE_THRESHOLDS.SMALL_READ_THRESHOLD) {
-                return await this.readLastNLinesReverse(filePath, requestedLines, mimeType, includeStatusMessage, totalLines);
+                return await this.readLastNLinesReverse(filePath, requestedLines, mimeType, includeStatusMessage, totalLines, signal);
             }
             else {
-                return await this.readFromEndWithReadline(filePath, requestedLines, mimeType, includeStatusMessage, totalLines);
+                return await this.readFromEndWithReadline(filePath, requestedLines, mimeType, includeStatusMessage, totalLines, signal);
             }
         }
         // For positive offsets
         else {
             if (fileSize < FILE_SIZE_LIMITS.LARGE_FILE_THRESHOLD || offset === 0) {
-                return await this.readFromStartWithReadline(filePath, offset, length, mimeType, includeStatusMessage, totalLines);
+                return await this.readFromStartWithReadline(filePath, offset, length, mimeType, includeStatusMessage, totalLines, signal);
             }
             else {
                 if (offset > READ_PERFORMANCE_THRESHOLDS.DEEP_OFFSET_THRESHOLD) {
-                    return await this.readFromEstimatedPosition(filePath, offset, length, mimeType, includeStatusMessage, totalLines);
+                    return await this.readFromEstimatedPosition(filePath, offset, length, mimeType, includeStatusMessage, totalLines, signal);
                 }
                 else {
-                    return await this.readFromStartWithReadline(filePath, offset, length, mimeType, includeStatusMessage, totalLines);
+                    return await this.readFromStartWithReadline(filePath, offset, length, mimeType, includeStatusMessage, totalLines, signal);
                 }
             }
         }
@@ -212,7 +212,7 @@ export class TextFileHandler {
     /**
      * Read last N lines efficiently by reading file backwards
      */
-    async readLastNLinesReverse(filePath, n, mimeType, includeStatusMessage = true, fileTotalLines) {
+    async readLastNLinesReverse(filePath, n, mimeType, includeStatusMessage = true, fileTotalLines, signal) {
         const fd = await fs.open(filePath, 'r');
         try {
             const stats = await fd.stat();
@@ -221,6 +221,11 @@ export class TextFileHandler {
             let lines = [];
             let partialLine = '';
             while (position > 0 && lines.length < n) {
+                if (signal?.aborted) {
+                    const err = new Error('Read aborted');
+                    err.code = 'ABORT_ERR';
+                    throw err;
+                }
                 const readSize = Math.min(READ_PERFORMANCE_THRESHOLDS.CHUNK_SIZE, position);
                 position -= readSize;
                 const buffer = Buffer.alloc(readSize);
@@ -247,9 +252,9 @@ export class TextFileHandler {
     /**
      * Read from end using readline with circular buffer
      */
-    async readFromEndWithReadline(filePath, requestedLines, mimeType, includeStatusMessage = true, fileTotalLines) {
+    async readFromEndWithReadline(filePath, requestedLines, mimeType, includeStatusMessage = true, fileTotalLines, signal) {
         const rl = createInterface({
-            input: createReadStream(filePath),
+            input: createReadStream(filePath, { signal }),
             crlfDelay: Infinity
         });
         const buffer = new Array(requestedLines);
@@ -279,9 +284,9 @@ export class TextFileHandler {
     /**
      * Read from start/middle using readline
      */
-    async readFromStartWithReadline(filePath, offset, length, mimeType, includeStatusMessage = true, fileTotalLines) {
+    async readFromStartWithReadline(filePath, offset, length, mimeType, includeStatusMessage = true, fileTotalLines, signal) {
         const rl = createInterface({
-            input: createReadStream(filePath),
+            input: createReadStream(filePath, { signal }),
             crlfDelay: Infinity
         });
         const result = [];
@@ -308,10 +313,10 @@ export class TextFileHandler {
     /**
      * Read from estimated byte position for very large files
      */
-    async readFromEstimatedPosition(filePath, offset, length, mimeType, includeStatusMessage = true, fileTotalLines) {
+    async readFromEstimatedPosition(filePath, offset, length, mimeType, includeStatusMessage = true, fileTotalLines, signal) {
         // First, do a quick scan to estimate lines per byte
         const rl = createInterface({
-            input: createReadStream(filePath),
+            input: createReadStream(filePath, { signal }),
             crlfDelay: Infinity
         });
         let sampleLines = 0;
@@ -324,7 +329,7 @@ export class TextFileHandler {
         }
         rl.close();
         if (sampleLines === 0) {
-            return await this.readFromStartWithReadline(filePath, offset, length, mimeType, includeStatusMessage, fileTotalLines);
+            return await this.readFromStartWithReadline(filePath, offset, length, mimeType, includeStatusMessage, fileTotalLines, signal);
         }
         // Estimate position
         const avgLineLength = bytesRead / sampleLines;
@@ -333,7 +338,7 @@ export class TextFileHandler {
         try {
             const stats = await fd.stat();
             const startPosition = Math.min(estimatedBytePosition, stats.size);
-            const stream = createReadStream(filePath, { start: startPosition });
+            const stream = createReadStream(filePath, { start: startPosition, signal });
             const rl2 = createInterface({
                 input: stream,
                 crlfDelay: Infinity

package/dist/utils/open-browser.d.ts

@@ -6,4 +6,4 @@ export declare function openBrowser(url: string): Promise<void>;
 /**
  * Open the Desktop Commander welcome page
  */
-export declare function openWelcomePage(): Promise<void>;
+export declare function openWelcomePage(clientName?: string): Promise<void>;

package/dist/utils/open-browser.js

@@ -37,7 +37,10 @@ export async function openBrowser(url) {
 /**
  * Open the Desktop Commander welcome page
  */
-export async function openWelcomePage() {
-    const url = 'https://desktopcommander.app/welcome/';
+export async function openWelcomePage(clientName) {
+    // utm_source is auto-captured by the welcome page's PostHog (and GA4), so
+    // web analytics can segment by MCP client without any web-side changes.
+    const url = 'https://desktopcommander.app/welcome/'
+        + (clientName ? `?utm_source=${encodeURIComponent(clientName)}` : '');
     await openBrowser(url);
 }

package/dist/utils/usageTracker.d.ts

@@ -38,7 +38,11 @@ declare class UsageTracker {
      */
     getStats(): Promise<ToolUsageStats>;
     /**
-     * Save usage stats to config
+     * Save usage stats to config.
+     * Non-blocking: the tool-call return path must not wait on a disk write. The
+     * in-memory stats are already updated by the caller (getStats returns the live
+     * config object), so persistence is coalesced in the background. This is what
+     * keeps a saturated libuv threadpool from gating tool responses on every call.
      */
     private saveStats;
     /**

package/dist/utils/usageTracker.js

@@ -45,10 +45,14 @@ class UsageTracker {
         return stats || this.getDefaultStats();
     }
     /**
-     * Save usage stats to config
+     * Save usage stats to config.
+     * Non-blocking: the tool-call return path must not wait on a disk write. The
+     * in-memory stats are already updated by the caller (getStats returns the live
+     * config object), so persistence is coalesced in the background. This is what
+     * keeps a saturated libuv threadpool from gating tool responses on every call.
      */
     async saveStats(stats) {
-        await configManager.setValue('usageStats', stats);
+        await configManager.setValueNonBlocking('usageStats', stats);
     }
     /**
      * Determine which category a tool belongs to
@@ -327,7 +331,14 @@ class UsageTracker {
     async shouldShowOnboarding() {
         // Check feature flag first (remote kill switch)
         const { featureFlagManager } = await import('./feature-flags.js');
-        const onboardingEnabled = featureFlagManager.get('onboarding_injection', true);
+        // Default false: on cold starts (no flag cache yet, e.g. ephemeral Docker
+        // containers) this can run before the background flag fetch completes.
+        // Treat an unknown flag as "off" so nothing is injected — flags load
+        // within seconds, so when the flag is ON onboarding still fires on a
+        // later call while the user is new. Deliberately no waiting here to keep
+        // tool calls latency-free.
+        // See: https://github.com/wonderwhy-er/DesktopCommanderMCP/issues/538
+        const onboardingEnabled = featureFlagManager.get('onboarding_injection', false);
         if (!onboardingEnabled) {
             return false;
         }