@adhdev/daemon-core 0.9.48 → 0.9.50

package/node_modules/@adhdev/session-host-core/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@adhdev/session-host-core",
-  "version": "0.9.48",
+  "version": "0.9.50",
   "description": "ADHDev local session host core \u2014 session registry, protocol, buffers",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@adhdev/daemon-core",
-  "version": "0.9.48",
+  "version": "0.9.50",
   "description": "ADHDev daemon core \u2014 CDP, IDE detection, providers, command execution",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",

package/src/cli-adapter-types.ts

@@ -41,6 +41,7 @@ export interface CliAdapter {
     sendMessage(text: string): Promise<void>;
     getStatus(): CliAdapterStatus;
     getScriptParsedStatus?(): unknown;
+    getDebugSnapshot?(): unknown;
     invokeScript?(scriptName: string, args?: Record<string, unknown>): Promise<unknown>;
     getPartialResponse(): string;
     saveAndStop?(): Promise<void>;

package/src/cli-adapters/provider-cli-adapter.ts

@@ -2545,6 +2545,88 @@ export class ProviderCliAdapter implements CliAdapter {
         return this.responseBuffer;
     }
 
+    getDebugSnapshot(): Record<string, unknown> {
+        const screenText = this.readTerminalScreenText();
+        const parsedResult = this.parsedStatusCache?.result && typeof this.parsedStatusCache.result === 'object'
+            ? this.parsedStatusCache.result as Record<string, any>
+            : null;
+        return {
+            cliType: this.cliType,
+            cliName: this.cliName,
+            workingDir: this.workingDir,
+            currentStatus: this.currentStatus,
+            ready: this.ready,
+            isWaitingForResponse: this.isWaitingForResponse,
+            activeModal: this.activeModal,
+            parseErrorMessage: this.parseErrorMessage,
+            messageCounts: {
+                committed: this.committedMessages.length,
+                structured: this.structuredMessages.length,
+                visible: this.messages.length,
+                parsedCache: Array.isArray(parsedResult?.messages) ? parsedResult.messages.length : undefined,
+            },
+            buffers: {
+                accumulatedLength: this.accumulatedBuffer.length,
+                accumulatedRawLength: this.accumulatedRawBuffer.length,
+                recentOutputLength: this.recentOutputBuffer.length,
+                responseLength: this.responseBuffer.length,
+                startupLength: this.startupBuffer.length,
+                accumulatedTail: this.accumulatedBuffer.slice(-24_000),
+                accumulatedRawTail: this.accumulatedRawBuffer.slice(-24_000),
+                recentOutputTail: this.recentOutputBuffer.slice(-12_000),
+                responseTail: this.responseBuffer.slice(-12_000),
+            },
+            terminal: {
+                screenText,
+                lastScreenSnapshot: this.lastScreenSnapshot,
+                lastScreenText: this.lastScreenText,
+                lastOutputAt: this.lastOutputAt,
+                lastNonEmptyOutputAt: this.lastNonEmptyOutputAt,
+                lastScreenChangeAt: this.lastScreenChangeAt,
+                lastScreenSnapshotReadAt: this.lastScreenSnapshotReadAt,
+            },
+            parser: {
+                scriptNames: listCliScriptNames(this.cliScripts),
+                traceSessionId: this.traceSessionId,
+                traceSeq: this.traceSeq,
+                currentTurnScope: this.currentTurnScope,
+                parsedStatusCache: parsedResult
+                    ? {
+                        id: parsedResult.id,
+                        status: parsedResult.status,
+                        title: parsedResult.title,
+                        providerSessionId: parsedResult.providerSessionId,
+                        transcriptAuthority: parsedResult.transcriptAuthority,
+                        coverage: parsedResult.coverage,
+                        messageCount: Array.isArray(parsedResult.messages) ? parsedResult.messages.length : undefined,
+                        activeModal: parsedResult.activeModal,
+                    }
+                    : null,
+                pendingScriptStatus: this.pendingScriptStatus,
+                pendingScriptStatusSince: this.pendingScriptStatusSince,
+            },
+            runtimeMetadata: this.getRuntimeMetadata(),
+            statusHistory: this.statusHistory.slice(-80),
+            traceEntries: this.traceEntries.slice(-120),
+            timing: {
+                spawnAt: this.spawnAt,
+                startupFirstOutputAt: this.startupFirstOutputAt,
+                submitPendingUntil: this.submitPendingUntil,
+                responseSettleIgnoreUntil: this.responseSettleIgnoreUntil,
+                responseEpoch: this.responseEpoch,
+                resizeSuppressUntil: this.resizeSuppressUntil,
+                lastApprovalResolvedAt: this.lastApprovalResolvedAt,
+                committedMessagesChangedAt: this.committedMessagesChangedAt,
+            },
+            finish: {
+                idleFinishCandidate: this.idleFinishCandidate,
+                finishRetryCount: this.finishRetryCount,
+                submitRetryUsed: this.submitRetryUsed,
+                submitRetryPromptSnippet: this.submitRetryPromptSnippet,
+            },
+        };
+    }
+
     getRuntimeMetadata(): PtyRuntimeMetadata | null {
         if (!this.ptyProcess || typeof this.ptyProcess.getMetadata !== 'function') return null;
         return this.ptyProcess.getMetadata();

package/src/cli-adapters/provider-cli-shared.ts

@@ -277,7 +277,12 @@ export function findBinary(name: string): string {
     const isWin = os.platform() === 'win32';
     try {
         const cmd = isWin ? `where ${trimmed}` : `which ${trimmed}`;
-        return execSync(cmd, { encoding: 'utf-8', timeout: 5000, stdio: ['pipe', 'pipe', 'pipe'] }).trim().split('\n')[0].trim();
+        return execSync(cmd, {
+            encoding: 'utf-8',
+            timeout: 5000,
+            stdio: ['pipe', 'pipe', 'pipe'],
+            ...(isWin ? { windowsHide: true } : {}),
+        }).trim().split('\n')[0].trim();
     } catch {
         return isWin ? `${trimmed}.cmd` : trimmed;
     }

package/src/commands/chat-commands.ts

@@ -10,8 +10,8 @@ import { assertProviderSupportsDeclaredInput, assertTextOnlyInput } from '../pro
 import { validateReadChatResultPayload } from '../providers/read-chat-contract.js';
 import type { ProviderInstance } from '../providers/provider-instance.js';
 import { readProviderChatHistory } from '../config/chat-history.js';
-import { LOG } from '../logging/logger.js';
-import { recordDebugTrace } from '../logging/debug-trace.js';
+import { LOG, getRecentLogs } from '../logging/logger.js';
+import { getRecentDebugTrace, recordDebugTrace } from '../logging/debug-trace.js';
 import { buildChatMessageSignature } from '../chat/chat-signatures.js';
 import type { ChatMessage } from '../types.js';
 import type { ReadChatCursor, ReadChatSyncMode, SessionTransport } from '../shared-types.js';
@@ -489,6 +489,275 @@ function buildReadChatCommandResult(payload: Record<string, any>, args: any): Co
     };
 }
 
+
+interface DebugSanitizeOptions {
+    maxDepth?: number;
+    maxArrayLength?: number;
+    maxObjectKeys?: number;
+    maxStringLength?: number;
+}
+
+const DEFAULT_DEBUG_SANITIZE_OPTIONS: Required<DebugSanitizeOptions> = {
+    maxDepth: 8,
+    maxArrayLength: 80,
+    maxObjectKeys: 120,
+    maxStringLength: 16_000,
+};
+
+const SECRET_KEY_PATTERN = /(?:token|secret|password|passwd|authorization|cookie|api[_-]?key|access[_-]?key|refresh[_-]?token|client[_-]?secret|private[_-]?key)/i;
+
+function truncateDebugString(value: string, maxLength: number): string {
+    if (value.length <= maxLength) return value;
+    return `${value.slice(0, maxLength)}…[truncated ${value.length - maxLength} chars]`;
+}
+
+function redactDebugSecrets(value: string): string {
+    return value
+        .replace(/(Authorization\s*:\s*Bearer\s+)[^\s'"`]+/gi, '$1[REDACTED:bearer]')
+        .replace(/(Bearer\s+)[A-Za-z0-9._~+\/-]{16,}=*/gi, '$1[REDACTED:bearer]')
+        .replace(/\b(?:gh[pousr]|github_pat)_[A-Za-z0-9_]{20,}\b/g, '[REDACTED:github-token]')
+        .replace(/\bsk-[A-Za-z0-9_-]{16,}\b/g, '[REDACTED:api-key]')
+        .replace(/\bxox[baprs]-[A-Za-z0-9-]{12,}\b/g, '[REDACTED:slack-token]')
+        .replace(/\b(?:adk|adm)_[A-Za-z0-9_-]{16,}\b/g, '[REDACTED:adhdev-token]')
+        .replace(/((?:api[_-]?key|token|secret|password|passwd|client[_-]?secret)\s*[:=]\s*)[^\s,'"`}&]+/gi, '$1[REDACTED:secret]')
+        .replace(/([?&](?:api[_-]?key|token|secret|password|client_secret)=)[^&#\s]+/gi, '$1[REDACTED:secret]');
+}
+
+export function sanitizeDebugBundleValue(
+    value: unknown,
+    options: DebugSanitizeOptions = {},
+    depth = 0,
+    keyHint = '',
+): unknown {
+    const normalizedOptions = { ...DEFAULT_DEBUG_SANITIZE_OPTIONS, ...options };
+    if (value === null || value === undefined) return value;
+    if (typeof value === 'number' || typeof value === 'boolean') return value;
+    if (typeof value === 'bigint') return String(value);
+    if (typeof value === 'string') {
+        if (SECRET_KEY_PATTERN.test(keyHint) && value.trim()) return '[REDACTED:secret-field]';
+        return truncateDebugString(redactDebugSecrets(value), normalizedOptions.maxStringLength);
+    }
+    if (typeof value === 'function') return `[Function ${value.name || 'anonymous'}]`;
+    if (typeof value !== 'object') return String(value);
+    if (depth >= normalizedOptions.maxDepth) return '[MaxDepth]';
+
+    if (Array.isArray(value)) {
+        const items = value
+            .slice(0, normalizedOptions.maxArrayLength)
+            .map((item) => sanitizeDebugBundleValue(item, normalizedOptions, depth + 1, keyHint));
+        if (value.length > normalizedOptions.maxArrayLength) {
+            items.push(`[truncated ${value.length - normalizedOptions.maxArrayLength} items]`);
+        }
+        return items;
+    }
+
+    const record = value as Record<string, unknown>;
+    const result: Record<string, unknown> = {};
+    const entries = Object.entries(record).slice(0, normalizedOptions.maxObjectKeys);
+    for (const [key, item] of entries) {
+        result[key] = sanitizeDebugBundleValue(item, normalizedOptions, depth + 1, key);
+    }
+    const remaining = Object.keys(record).length - entries.length;
+    if (remaining > 0) result.__truncatedKeys = remaining;
+    return result;
+}
+
+function summarizeProviderForDebug(provider: ProviderModule | undefined): Record<string, unknown> | null {
+    if (!provider) return null;
+    const scripts = provider.scripts && typeof provider.scripts === 'object'
+        ? Object.keys(provider.scripts)
+        : [];
+    const controls = Array.isArray((provider as any).controls)
+        ? (provider as any).controls.map((control: any) => ({
+            id: control?.id,
+            label: control?.label,
+            type: control?.type,
+            settingKey: control?.settingKey,
+            invokeScript: control?.invokeScript,
+            listScript: control?.listScript,
+            location: control?.location,
+        }))
+        : [];
+    return {
+        type: provider.type,
+        name: provider.name,
+        category: provider.category,
+        version: (provider as any).version,
+        canonicalHistory: provider.canonicalHistory,
+        historyBehavior: provider.historyBehavior,
+        webviewMatchText: provider.webviewMatchText,
+        scriptNames: scripts,
+        controls,
+        resume: provider.resume,
+    };
+}
+
+function summarizeSessionForDebug(session: any): Record<string, unknown> | null {
+    if (!session || typeof session !== 'object') return null;
+    return {
+        sessionId: session.sessionId,
+        instanceKey: session.instanceKey,
+        adapterKey: session.adapterKey,
+        providerType: session.providerType,
+        providerName: session.providerName,
+        transport: session.transport,
+        kind: session.kind,
+        cdpManagerKey: session.cdpManagerKey,
+        parentSessionId: session.parentSessionId,
+        providerSessionId: session.providerSessionId,
+        workspace: session.workspace,
+        title: session.title,
+        status: session.status,
+        mode: session.mode,
+        capabilities: session.capabilities,
+    };
+}
+
+function summarizeStateForDebug(state: any): Record<string, unknown> | null {
+    if (!state || typeof state !== 'object') return null;
+    const activeChat = state.activeChat && typeof state.activeChat === 'object' ? state.activeChat : null;
+    return {
+        type: state.type,
+        name: state.name,
+        category: state.category,
+        status: state.status,
+        instanceId: state.instanceId,
+        providerSessionId: state.providerSessionId,
+        title: state.title,
+        transport: state.transport,
+        mode: state.mode,
+        workspace: state.workspace,
+        runtime: state.runtime,
+        errorMessage: state.errorMessage,
+        errorReason: state.errorReason,
+        activeChat: activeChat ? {
+            status: activeChat.status,
+            title: activeChat.title,
+            messageCount: Array.isArray(activeChat.messages) ? activeChat.messages.length : undefined,
+            activeModal: activeChat.activeModal,
+            messagesTail: Array.isArray(activeChat.messages) ? activeChat.messages.slice(-10) : undefined,
+        } : null,
+        controlValues: state.controlValues,
+        summaryMetadata: state.summaryMetadata,
+    };
+}
+
+function buildDebugBundleText(bundle: Record<string, unknown>): string {
+    return [
+        '# ADHDev Chat Debug Bundle',
+        '',
+        '```json',
+        JSON.stringify(bundle, null, 2),
+        '```',
+    ].join('\n');
+}
+
+export async function handleGetChatDebugBundle(h: CommandHelpers, args: any): Promise<CommandResult> {
+    const targetSessionId = typeof args?.targetSessionId === 'string' ? args.targetSessionId.trim() : '';
+    if (!targetSessionId && !h.currentSession) {
+        return { success: false, error: 'No targetSessionId specified — cannot route command' };
+    }
+
+    const provider = h.getProvider(args?.agentType);
+    const transport = getTargetTransport(h, provider);
+    const providerType = provider?.type || getCurrentProviderType(h, args?.agentType || '');
+    const adapter = isCliLikeTransport(transport) ? getTargetedCliAdapter(h, args, provider?.type) : null;
+    const targetInstance = getTargetInstance(h, args);
+
+    let adapterStatus: unknown = null;
+    let parsedStatus: unknown = null;
+    let adapterDebugSnapshot: unknown = null;
+    let partialResponse = '';
+    if (adapter) {
+        try { adapterStatus = adapter.getStatus?.(); } catch (error: any) { adapterStatus = { error: error?.message || String(error) }; }
+        try { parsedStatus = typeof adapter.getScriptParsedStatus === 'function' ? parseMaybeJson(adapter.getScriptParsedStatus()) : null; } catch (error: any) { parsedStatus = { error: error?.message || String(error) }; }
+        try { adapterDebugSnapshot = typeof adapter.getDebugSnapshot === 'function' ? adapter.getDebugSnapshot() : null; } catch (error: any) { adapterDebugSnapshot = { error: error?.message || String(error) }; }
+        try { partialResponse = adapter.getPartialResponse?.() || ''; } catch { partialResponse = ''; }
+    }
+
+    let instanceState: unknown = null;
+    if (targetInstance?.getState) {
+        try { instanceState = summarizeStateForDebug(targetInstance.getState()); } catch (error: any) { instanceState = { error: error?.message || String(error) }; }
+    }
+
+    let readChat: unknown = null;
+    try {
+        const readResult = await handleReadChat(h, { ...args, tailLimit: Math.max(1, Math.min(40, Number(args?.tailLimit || 40))) });
+        readChat = readResult.success
+            ? {
+                success: true,
+                status: readResult.status,
+                title: readResult.title,
+                totalMessages: readResult.totalMessages,
+                returnedMessages: Array.isArray(readResult.messages) ? readResult.messages.length : undefined,
+                syncMode: readResult.syncMode,
+                replaceFrom: readResult.replaceFrom,
+                lastMessageSignature: readResult.lastMessageSignature,
+                providerSessionId: readResult.providerSessionId,
+                transcriptAuthority: readResult.transcriptAuthority,
+                coverage: readResult.coverage,
+                activeModal: readResult.activeModal,
+                messagesTail: Array.isArray(readResult.messages) ? readResult.messages.slice(-20) : [],
+                debugReadChat: readResult.debugReadChat,
+            }
+            : { success: false, error: readResult.error };
+    } catch (error: any) {
+        readChat = { success: false, error: error?.message || String(error) };
+    }
+
+    const cdp = h.getCdp();
+    const rawBundle: Record<string, unknown> = {
+        version: 1,
+        createdAt: new Date().toISOString(),
+        target: {
+            targetSessionId,
+            providerType,
+            transport,
+            routeManagerKey: h.currentManagerKey,
+            currentIdeType: h.currentIdeType,
+        },
+        session: summarizeSessionForDebug(h.currentSession),
+        provider: summarizeProviderForDebug(provider),
+        daemon: {
+            pid: process.pid,
+            platform: process.platform,
+            nodeVersion: process.version,
+            cwd: process.cwd(),
+        },
+        cdp: {
+            requested: !!cdp,
+            connected: !!cdp?.isConnected,
+            managerKey: getCurrentManagerKey(h),
+        },
+        instanceState,
+        cli: adapter ? {
+            cliType: adapter.cliType,
+            cliName: adapter.cliName,
+            workingDir: adapter.workingDir,
+            status: (adapterStatus as any)?.status,
+            activeModal: (adapterStatus as any)?.activeModal,
+            messageCount: Array.isArray((adapterStatus as any)?.messages) ? (adapterStatus as any).messages.length : undefined,
+            messagesTail: Array.isArray((adapterStatus as any)?.messages) ? (adapterStatus as any).messages.slice(-20) : undefined,
+            parsedStatus,
+            partialResponse,
+            ready: typeof adapter.isReady === 'function' ? adapter.isReady() : undefined,
+            processing: typeof adapter.isProcessing === 'function' ? adapter.isProcessing() : undefined,
+            debugSnapshot: adapterDebugSnapshot,
+        } : null,
+        readChat,
+        frontend: args?.frontendSnapshot && typeof args.frontendSnapshot === 'object' ? args.frontendSnapshot : null,
+        recentLogs: getRecentLogs(80, 'debug'),
+        recentDebugTrace: getRecentDebugTrace({ limit: 120 }),
+    };
+
+    const bundle = sanitizeDebugBundleValue(rawBundle) as Record<string, unknown>;
+    return {
+        success: true,
+        bundle,
+        text: buildDebugBundleText(bundle),
+    };
+}
+
 function didProviderConfirmSend(result: any): boolean {
     const parsed = parseMaybeJson(result);
     if (parsed === true) return true;

package/src/commands/cli-manager.ts

@@ -52,7 +52,10 @@ function commandExists(command: string): boolean {
         return existsSync(expandExecutable(trimmed));
     }
     try {
-        execFileSync(process.platform === 'win32' ? 'where' : 'which', [trimmed], { stdio: 'ignore' });
+        execFileSync(process.platform === 'win32' ? 'where' : 'which', [trimmed], {
+            stdio: 'ignore',
+            ...(process.platform === 'win32' ? { windowsHide: true } : {}),
+        });
         return true;
     } catch {
         return false;

package/src/commands/handler.ts

@@ -380,6 +380,7 @@ export class DaemonCommandHandler implements CommandHelpers {
 
         const sessionScopedCommands = new Set([
             'read_chat',
+            'get_chat_debug_bundle',
             'send_chat',
             'list_chats',
             'new_chat',
@@ -431,6 +432,7 @@ export class DaemonCommandHandler implements CommandHelpers {
         switch (cmd) {
             // ─── Chat commands (chat-commands.ts) ───────────────
             case 'read_chat': return Chat.handleReadChat(this, args);
+            case 'get_chat_debug_bundle': return Chat.handleGetChatDebugBundle(this, args);
             case 'chat_history': return Chat.handleChatHistory(this, args);
             case 'send_chat': return Chat.handleSendChat(this, args);
             case 'list_chats': return Chat.handleListChats(this, args);

package/src/commands/router.ts

@@ -36,7 +36,7 @@ import { getSessionHostSurfaceKind, partitionSessionHostRecords } from '../sessi
 import { buildSessionEntries } from '../status/builders.js';
 import { buildMachineInfo, buildStatusSnapshot } from '../status/snapshot.js';
 import { getSessionCompletionMarker } from '../status/snapshot.js';
-import { spawnDetachedDaemonUpgradeHelper } from './upgrade-helper.js';
+import { execNpmCommandSync, resolveCurrentGlobalInstallSurface, spawnDetachedDaemonUpgradeHelper } from './upgrade-helper.js';
 import * as fs from 'fs';
 
 // ─── Types ───
@@ -525,6 +525,12 @@ export class DaemonCommandRouter {
                 const wantsAll = args?.all === true;
                 const offset = wantsAll ? 0 : Math.max(0, Number(args?.offset) || 0);
                 const limit = wantsAll ? Number.MAX_SAFE_INTEGER : Math.max(1, Math.min(100, Number(args?.limit) || 30));
+                const requestedWorkspace = typeof args?.workspace === 'string' ? args.workspace.trim() : '';
+                const requestedProviderSessionId = typeof args?.providerSessionId === 'string'
+                    ? args.providerSessionId.trim()
+                    : typeof args?.activeProviderSessionId === 'string'
+                        ? args.activeProviderSessionId.trim()
+                        : '';
                 const providerMeta = this.deps.providerLoader.resolve?.(providerType) || this.deps.providerLoader.getMeta(providerType);
                 const { sessions: historySessions, hasMore, source } = listProviderHistorySessions(providerType, {
                     canonicalHistory: providerMeta?.canonicalHistory,
@@ -546,6 +552,10 @@ export class DaemonCommandRouter {
                     sessions: historySessions.map(session => {
                         const saved = savedSessionById.get(session.historySessionId);
                         const recent = recentSessionById.get(session.historySessionId);
+                        const workspace = saved?.workspace
+                            || recent?.workspace
+                            || session.workspace
+                            || (requestedWorkspace && requestedProviderSessionId === session.historySessionId ? requestedWorkspace : undefined);
                         return {
                             id: session.historySessionId,
                             providerSessionId: session.historySessionId,
@@ -553,13 +563,13 @@ export class DaemonCommandRouter {
                             providerName: saved?.providerName || recent?.providerName || providerType,
                             kind: saved?.kind || recent?.kind || kind,
                             title: saved?.title || recent?.title || session.sessionTitle || session.preview || providerType,
-                            workspace: saved?.workspace || recent?.workspace || session.workspace,
+                            workspace,
                             summaryMetadata: saved?.summaryMetadata || recent?.summaryMetadata,
                             preview: session.preview,
                             messageCount: session.messageCount,
                             firstMessageAt: session.firstMessageAt,
                             lastMessageAt: session.lastMessageAt,
-                            canResume: !!(saved?.workspace || recent?.workspace || session.workspace) && canResumeById,
+                            canResume: !!workspace && canResumeById,
                             historySource: session.source,
                             sourcePath: session.sourcePath,
                             sourceMtimeMs: session.sourceMtimeMs,
@@ -847,23 +857,22 @@ export class DaemonCommandRouter {
             case 'daemon_upgrade': {
                 LOG.info('Upgrade', 'Remote upgrade requested from dashboard');
                 try {
-                    const { execSync } = await import('child_process');
-
                     // Detect package name for upgrade
                     const isStandalone = this.deps.packageName === '@adhdev/daemon-standalone'
                         || process.argv[1]?.includes('daemon-standalone');
                     const pkgName = isStandalone ? '@adhdev/daemon-standalone' : 'adhdev';
+                    const npmSurface = resolveCurrentGlobalInstallSurface({ packageName: pkgName });
 
                     // Check latest version
-                    const latest = execSync(`npm view ${pkgName} version`, { encoding: 'utf-8', timeout: 10000 }).trim();
+                    const latest = String(execNpmCommandSync(['view', pkgName, 'version'], { encoding: 'utf-8', timeout: 10000 }, npmSurface)).trim();
                     LOG.info('Upgrade', `Latest ${pkgName}: v${latest}`);
                     let currentInstalled: string | null = null;
                     try {
-                        const currentJson = execSync(`npm ls -g ${pkgName} --depth=0 --json`, {
+                        const currentJson = String(execNpmCommandSync(['ls', '-g', pkgName, '--depth=0', '--json'], {
                             encoding: 'utf-8',
                             timeout: 10000,
                             stdio: ['pipe', 'pipe', 'pipe'],
-                        }).trim();
+                        }, npmSurface)).trim();
                         const parsed = JSON.parse(currentJson);
                         currentInstalled = parsed?.dependencies?.[pkgName]?.version || null;
                     } catch {

package/src/commands/upgrade-helper.ts

@@ -1,4 +1,4 @@
-import { execFileSync } from 'child_process';
+import { execFileSync, type ExecFileSyncOptions } from 'child_process';
 import { spawn } from 'child_process';
 import * as fs from 'fs';
 import * as os from 'os';
@@ -20,16 +20,18 @@ export interface CurrentGlobalInstallSurface {
   npmArgsPrefix?: string[];
   packageRoot: string | null;
   installPrefix: string | null;
-  execOptions?: { shell: boolean };
+  execOptions?: NpmExecOptions;
 }
 
 export interface PinnedGlobalInstallCommand {
   command: string;
   args: string[];
   surface: CurrentGlobalInstallSurface;
-  execOptions: { shell: boolean };
+  execOptions: NpmExecOptions;
 }
 
+export type NpmExecOptions = { shell: boolean; windowsHide?: boolean };
+
 function getUpgradeLogPath(): string {
   const home = os.homedir();
   const dir = path.join(home, '.adhdev');
@@ -49,29 +51,29 @@ function appendUpgradeLog(message: string): void {
 function resolveSiblingNpmInvocation(nodeExecutable: string, platform: NodeJS.Platform = process.platform): {
   executable: string;
   argsPrefix: string[];
-  execOptions: { shell: boolean };
+  execOptions: NpmExecOptions;
 } {
   const binDir = path.dirname(nodeExecutable);
   if (platform === 'win32') {
     const npmCliPath = path.join(binDir, 'node_modules', 'npm', 'bin', 'npm-cli.js');
     if (fs.existsSync(npmCliPath)) {
-      return { executable: nodeExecutable, argsPrefix: [npmCliPath], execOptions: { shell: false } };
+      return { executable: nodeExecutable, argsPrefix: [npmCliPath], execOptions: getNpmExecOptions(platform) };
     }
     for (const candidate of ['npm.exe', 'npm']) {
       const candidatePath = path.join(binDir, candidate);
       if (fs.existsSync(candidatePath)) {
-        return { executable: candidatePath, argsPrefix: [], execOptions: { shell: false } };
+        return { executable: candidatePath, argsPrefix: [], execOptions: getNpmExecOptions(platform) };
       }
     }
-    return { executable: nodeExecutable, argsPrefix: [npmCliPath], execOptions: { shell: false } };
+    return { executable: nodeExecutable, argsPrefix: [npmCliPath], execOptions: getNpmExecOptions(platform) };
   }
   for (const candidate of ['npm']) {
     const candidatePath = path.join(binDir, candidate);
     if (fs.existsSync(candidatePath)) {
-      return { executable: candidatePath, argsPrefix: [], execOptions: { shell: false } };
+      return { executable: candidatePath, argsPrefix: [], execOptions: getNpmExecOptions(platform) };
     }
   }
-  return { executable: 'npm', argsPrefix: [], execOptions: { shell: false } };
+  return { executable: 'npm', argsPrefix: [], execOptions: getNpmExecOptions(platform) };
 }
 
 function findCurrentPackageRoot(currentCliPath: string | undefined, packageName: string): string | null {
@@ -167,14 +169,34 @@ export function buildPinnedGlobalInstallCommand(options: {
   };
 }
 
-function getNpmExecOptions(_platform: NodeJS.Platform = process.platform): { shell: boolean } {
+export function getNpmExecOptions(platform: NodeJS.Platform = process.platform): NpmExecOptions {
+  if (platform === 'win32') {
+    return { shell: false, windowsHide: true };
+  }
   return { shell: false };
 }
 
+export function execNpmCommandSync(
+  args: string[],
+  options: ExecFileSyncOptions = {},
+  surface?: Pick<CurrentGlobalInstallSurface, 'npmExecutable' | 'npmArgsPrefix' | 'execOptions'>,
+): Buffer | string {
+  const execOptions = surface?.execOptions || getNpmExecOptions();
+  return execFileSync(
+    surface?.npmExecutable || 'npm',
+    [...(surface?.npmArgsPrefix || []), ...args],
+    {
+      ...options,
+      ...execOptions,
+      ...(process.platform === 'win32' ? { windowsHide: true } : {}),
+    },
+  );
+}
+
 function killPid(pid: number): boolean {
   try {
     if (process.platform === 'win32') {
-      execFileSync('taskkill', ['/PID', String(pid), '/T', '/F'], { stdio: 'ignore' });
+      execFileSync('taskkill', ['/PID', String(pid), '/T', '/F'], { stdio: 'ignore', windowsHide: true });
     } else {
       process.kill(pid, 'SIGTERM');
     }
@@ -193,7 +215,7 @@ function getWindowsProcessCommandLine(pid: number): string | null {
       '-ExecutionPolicy', 'Bypass',
       '-Command',
       `(Get-CimInstance Win32_Process -Filter "${pidFilter}").CommandLine`,
-    ], { encoding: 'utf8', timeout: 5000, stdio: ['ignore', 'pipe', 'ignore'] }).trim();
+    ], { encoding: 'utf8', timeout: 5000, stdio: ['ignore', 'pipe', 'ignore'], windowsHide: true }).trim();
     if (psOut) return psOut;
   } catch {
     // fall through to wmic fallback
@@ -202,7 +224,7 @@ function getWindowsProcessCommandLine(pid: number): string | null {
   try {
     const wmicOut = execFileSync('wmic', [
       'process', 'where', pidFilter, 'get', 'CommandLine',
-    ], { encoding: 'utf8', timeout: 3000, stdio: ['ignore', 'pipe', 'ignore'] }).trim();
+    ], { encoding: 'utf8', timeout: 3000, stdio: ['ignore', 'pipe', 'ignore'], windowsHide: true }).trim();
     if (wmicOut) return wmicOut;
   } catch {
     // noop
@@ -273,10 +295,10 @@ function removeDaemonPidFile(): void {
 
 function cleanupStaleGlobalInstallDirs(pkgName: string, surface: CurrentGlobalInstallSurface): void {
   const prefixArgs = surface.installPrefix ? ['--prefix', surface.installPrefix] : [];
-  const npmRoot = execFileSync(surface.npmExecutable, [...(surface.npmArgsPrefix || []), 'root', '-g', ...prefixArgs], { encoding: 'utf8', ...surface.execOptions }).trim();
+  const npmRoot = String(execNpmCommandSync(['root', '-g', ...prefixArgs], { encoding: 'utf8' }, surface)).trim();
   if (!npmRoot) return;
   const npmPrefix = surface.installPrefix
-    || execFileSync(surface.npmExecutable, [...(surface.npmArgsPrefix || []), 'prefix', '-g', ...prefixArgs], { encoding: 'utf8', ...surface.execOptions }).trim();
+    || String(execNpmCommandSync(['prefix', '-g', ...prefixArgs], { encoding: 'utf8' }, surface)).trim();
   const binDir = process.platform === 'win32' ? npmPrefix : path.join(npmPrefix, 'bin');
   const packageBaseName = pkgName.startsWith('@') ? pkgName.split('/')[1] : pkgName;
   const binNames = new Set<string>([packageBaseName]);