evolcore 0.0.20 → 0.0.21

package/dist/ipc.js

@@ -1,5 +1,6 @@
 import net from 'net';
 import { performance } from 'node:perf_hooks';
+import { Worker } from 'node:worker_threads';
 import fs from 'fs';
 import crypto from 'crypto';
 import os from 'os';
@@ -9,14 +10,20 @@ import { withMenuProcessingTime, logMenuRequestCompleted, logMenuRequestReceived
 import { fileCache } from './core/daemon-file-cache.js';
 import { HANDOFF_QUERY_MAX_LIMIT, HANDOFF_STATES } from './core/handoff/types.js';
 import { AgentReloadBusyError } from './core/agent-reload-coordinator.js';
-import { resolvePaths } from './paths.js';
+import { getWindowsInstanceSocketPathCandidates, resolvePaths } from './paths.js';
 import { getProcessStartTime, isSameOrOlderProcess } from './utils/process-introspect.js';
-import { classifyProcessTree, ProcessTreeSampler } from './utils/process-tree-stats.js';
+import { classifyProcessTree, ProcessTreeSampler, readProcessMetrics } from './utils/process-tree-stats.js';
 import { readSystemMemoryUsage } from './utils/system-memory.js';
 import { hashCurrentDelegatedCommand } from './core/auth/agent-delegation.js';
 import { normalizeAunMentionEntries } from './aun/msg/mention-schema.js';
 const isWindows = process.platform === 'win32';
 const isNamedPipe = (p) => isWindows && p.startsWith('\\\\.\\pipe\\');
+const CPU_SAMPLE_INTERVAL_MS = 1000;
+const PROCESS_TREE_SAMPLE_INTERVAL_MS = 5000;
+const PROCESS_TREE_SAMPLE_WARN_MS = 250;
+const EVENT_LOOP_LAG_WARN_MS = 100;
+const SAMPLE_WARN_LOG_INTERVAL_MS = 60_000;
+const PROCESS_TREE_WORKER_REQUEST_TIMEOUT_MS = 15_000;
 const finiteTimestamp = (value) => (typeof value === 'number' && Number.isFinite(value) ? value : undefined);
 const LOCAL_CONTROL_COMMANDS = new Set([
     'bind.begin',
@@ -38,6 +45,22 @@ const LOCAL_CONTROL_COMMANDS = new Set([
     'monitor-snapshot',
     'shutdown',
 ]);
+let ipcQuerySequence = 0;
+function ipcLogToken(value, fallback = 'unknown') {
+    const token = String(value ?? '').replace(/[^A-Za-z0-9_.:-]/g, '_').slice(0, 128);
+    return token || fallback;
+}
+function nextIpcQueryId(cmd) {
+    const payload = cmd.payload;
+    const nestedId = payload && typeof payload === 'object' && !Array.isArray(payload)
+        ? payload.requestId ?? payload.id
+        : undefined;
+    const supplied = cmd.requestId ?? cmd.id ?? nestedId;
+    if (typeof supplied === 'string' || typeof supplied === 'number')
+        return ipcLogToken(supplied, 'unknown');
+    ipcQuerySequence = (ipcQuerySequence + 1) % Number.MAX_SAFE_INTEGER;
+    return `ipc-${ipcQuerySequence}`;
+}
 function requiresLocalControlToken(cmd) {
     // Managed bootstrap completion is authenticated by the session delegation
     // ticket. A standalone CLI invocation still needs the daemon control token.
@@ -62,6 +85,7 @@ export class IpcServer {
     commandExecutor;
     server = null;
     agentRegistry;
+    agentApplicationService;
     aunAidProvider;
     aunAidStatsProvider;
     aunAidStatsRecorder;
@@ -108,9 +132,28 @@ export class IpcServer {
     sysCpuPercent = 0; // 系统级
     lastCpuTimes = null;
     cpuTimer = null;
+    processTreeTimer = null;
+    processTreeWorker = null;
+    processTreeWorkerRequestId = 0;
+    processTreeWorkerRequestStartedAt = 0;
+    processTreeWorkerRequestTimer = null;
+    processTreeSamplingInFlight = false;
+    lastCpuTickMono = null;
+    eventLoopLagMs = 0;
+    maxEventLoopLagMs = 0;
+    lastSampleWarningAt = 0;
     processTreeSampler = new ProcessTreeSampler(process.pid);
     processTreeSnapshot = null;
     associatedProcessKinds = new Map();
+    processTreeSampling = {
+        lastDurationMs: 0,
+        maxDurationMs: 0,
+        lastSampleAt: 0,
+        associatedRootCount: 0,
+        processCount: 0,
+        inFlight: false,
+        lastError: null,
+    };
     constructor(socketPath, getStatus, commandExecutor) {
         this.socketPath = socketPath;
         this.getStatus = getStatus;
@@ -120,6 +163,10 @@ export class IpcServer {
     setAgentRegistry(registry) {
         this.agentRegistry = registry;
     }
+    /** Inject the Core-owned agent application facade for in-process handlers. */
+    setAgentApplicationService(service) {
+        this.agentApplicationService = service;
+    }
     /** Authenticate local control-plane callers that cannot use task delegation. */
     setControlToken(token) {
         this.controlToken = Buffer.from(token);
@@ -249,12 +296,23 @@ export class IpcServer {
     setWechatContactBindExecutor(executor) {
         this.wechatContactBindExecutor = executor;
     }
-    /** Start the 1s background CPU sampling loop (for monitor-snapshot). Call after start(). */
+    /** Start the background CPU and process-tree sampling loops. Call after start(). */
     startCpuTracking() {
         if (this.cpuTimer)
             return;
         this.sampleProcessTree();
+        this.lastCpuTickMono = performance.now();
         this.cpuTimer = setInterval(() => {
+            const tickMono = performance.now();
+            if (this.lastCpuTickMono !== null) {
+                const lagMs = Math.max(0, tickMono - this.lastCpuTickMono - CPU_SAMPLE_INTERVAL_MS);
+                this.eventLoopLagMs = Math.round(lagMs * 10) / 10;
+                this.maxEventLoopLagMs = Math.max(this.maxEventLoopLagMs, this.eventLoopLagMs);
+                if (this.eventLoopLagMs >= EVENT_LOOP_LAG_WARN_MS) {
+                    logger.debug(`[IPC] cpu_sample event_loop_lag_ms=${this.eventLoopLagMs}`);
+                }
+            }
+            this.lastCpuTickMono = tickMono;
             const now = Date.now();
             const elapsedUs = (now - this.lastCpuTs) * 1000; // wall time in microseconds
             if (elapsedUs > 0) {
@@ -281,30 +339,213 @@ export class IpcServer {
                 this.lastCpuTimes = { idle, total };
             }
             catch { /* os.cpus() 理论上不抛 */ }
-            this.sampleProcessTree();
-        }, 1000);
+        }, CPU_SAMPLE_INTERVAL_MS);
         // Don't keep the event loop alive for sampling alone.
         this.cpuTimer.unref?.();
+        // Process enumeration is substantially more expensive on Windows than
+        // process.cpuUsage()/os.cpus(), so keep it at a lower refresh rate.
+        this.processTreeTimer = setInterval(() => this.sampleProcessTree(), PROCESS_TREE_SAMPLE_INTERVAL_MS);
+        this.processTreeTimer.unref?.();
     }
-    /** Stop the CPU sampling loop. */
+    /** Stop the CPU and process-tree sampling loops. */
     stopCpuTracking() {
         if (this.cpuTimer) {
             clearInterval(this.cpuTimer);
             this.cpuTimer = null;
         }
+        if (this.processTreeTimer) {
+            clearInterval(this.processTreeTimer);
+            this.processTreeTimer = null;
+        }
+        if (this.processTreeWorkerRequestTimer) {
+            clearTimeout(this.processTreeWorkerRequestTimer);
+            this.processTreeWorkerRequestTimer = null;
+        }
+        this.processTreeSamplingInFlight = false;
+        this.processTreeSampling.inFlight = false;
+        // Invalidate callbacks from a worker that is being stopped. Its error and
+        // exit events are asynchronous and must not turn an intentional shutdown
+        // into a failed sample.
+        this.processTreeWorkerRequestId++;
+        this.processTreeWorkerRequestStartedAt = 0;
+        const worker = this.processTreeWorker;
+        this.processTreeWorker = null;
+        if (worker)
+            void worker.terminate();
+        this.lastCpuTickMono = null;
     }
     sampleProcessTree() {
+        if (isWindows) {
+            this.sampleProcessTreeInWorker();
+            return;
+        }
+        const startedAt = performance.now();
+        try {
+            this.commitProcessTreeSample(readProcessMetrics(), performance.now() - startedAt);
+        }
+        catch (error) {
+            this.recordProcessTreeSampleError(error, performance.now() - startedAt);
+        }
+    }
+    sampleProcessTreeInWorker() {
+        if (this.processTreeSamplingInFlight)
+            return;
+        const worker = this.getProcessTreeWorker();
+        if (!worker)
+            return;
+        this.processTreeSamplingInFlight = true;
+        this.processTreeSampling.inFlight = true;
+        this.processTreeWorkerRequestStartedAt = performance.now();
+        const requestId = ++this.processTreeWorkerRequestId;
+        const startedAt = this.processTreeWorkerRequestStartedAt;
+        this.processTreeWorkerRequestTimer = setTimeout(() => {
+            if (this.processTreeWorker !== worker
+                || !this.processTreeSamplingInFlight
+                || this.processTreeWorkerRequestId !== requestId)
+                return;
+            this.processTreeSamplingInFlight = false;
+            this.processTreeSampling.inFlight = false;
+            this.processTreeWorkerRequestTimer = null;
+            this.processTreeWorkerRequestId++;
+            this.processTreeWorkerRequestStartedAt = 0;
+            this.processTreeWorker = null;
+            void worker.terminate();
+            this.recordProcessTreeSampleError(`process-tree worker request timed out after ${PROCESS_TREE_WORKER_REQUEST_TIMEOUT_MS}ms`, performance.now() - startedAt);
+        }, PROCESS_TREE_WORKER_REQUEST_TIMEOUT_MS);
+        this.processTreeWorkerRequestTimer.unref?.();
+        try {
+            worker.postMessage({ type: 'sample', requestId });
+        }
+        catch (error) {
+            if (this.processTreeWorker !== worker || this.processTreeWorkerRequestId !== requestId)
+                return;
+            if (this.processTreeWorkerRequestTimer) {
+                clearTimeout(this.processTreeWorkerRequestTimer);
+                this.processTreeWorkerRequestTimer = null;
+            }
+            this.processTreeSamplingInFlight = false;
+            this.processTreeSampling.inFlight = false;
+            this.processTreeWorkerRequestId++;
+            this.processTreeWorkerRequestStartedAt = 0;
+            this.processTreeWorker = null;
+            void worker.terminate();
+            this.recordProcessTreeSampleError(error, performance.now() - startedAt);
+        }
+    }
+    getProcessTreeWorker() {
+        if (this.processTreeWorker)
+            return this.processTreeWorker;
+        try {
+            const worker = new Worker(new URL('./utils/process-tree-worker.js', import.meta.url));
+            worker.unref();
+            worker.on('message', (message) => {
+                if (this.processTreeWorker !== worker
+                    || !this.processTreeSamplingInFlight
+                    || message.requestId !== this.processTreeWorkerRequestId)
+                    return;
+                if (this.processTreeWorkerRequestTimer) {
+                    clearTimeout(this.processTreeWorkerRequestTimer);
+                    this.processTreeWorkerRequestTimer = null;
+                }
+                this.processTreeSamplingInFlight = false;
+                this.processTreeSampling.inFlight = false;
+                const durationMs = typeof message.durationMs === 'number'
+                    ? message.durationMs
+                    : performance.now() - this.processTreeWorkerRequestStartedAt;
+                if (message.type === 'sample' && Array.isArray(message.metrics)) {
+                    this.commitProcessTreeSample(message.metrics, durationMs);
+                }
+                else {
+                    this.recordProcessTreeSampleError(message.error ?? 'process-tree worker failed', durationMs);
+                }
+            });
+            worker.on('error', error => {
+                if (this.processTreeWorker !== worker)
+                    return;
+                const wasInFlight = this.processTreeSamplingInFlight;
+                if (this.processTreeWorkerRequestTimer) {
+                    clearTimeout(this.processTreeWorkerRequestTimer);
+                    this.processTreeWorkerRequestTimer = null;
+                }
+                this.processTreeWorker = null;
+                if (!wasInFlight)
+                    return;
+                this.processTreeSamplingInFlight = false;
+                this.processTreeSampling.inFlight = false;
+                this.processTreeWorkerRequestId++;
+                this.recordProcessTreeSampleError(error, performance.now() - this.processTreeWorkerRequestStartedAt);
+            });
+            worker.on('exit', code => {
+                if (this.processTreeWorker !== worker)
+                    return;
+                const wasInFlight = this.processTreeSamplingInFlight;
+                if (this.processTreeWorkerRequestTimer) {
+                    clearTimeout(this.processTreeWorkerRequestTimer);
+                    this.processTreeWorkerRequestTimer = null;
+                }
+                this.processTreeWorker = null;
+                if (code !== 0 && wasInFlight) {
+                    this.processTreeSamplingInFlight = false;
+                    this.processTreeSampling.inFlight = false;
+                    this.processTreeWorkerRequestId++;
+                    this.recordProcessTreeSampleError(`process-tree worker exited with code ${code}`, performance.now() - this.processTreeWorkerRequestStartedAt);
+                }
+            });
+            this.processTreeWorker = worker;
+            return worker;
+        }
+        catch (error) {
+            this.recordProcessTreeSampleError(error, 0);
+            return null;
+        }
+    }
+    commitProcessTreeSample(metrics, durationMs) {
+        let roots = [];
+        let processCount = 0;
         try {
-            const roots = this.readAssociatedProcessRoots();
+            let processStartTimes;
+            if (isWindows) {
+                const starts = new Map();
+                for (const metric of metrics) {
+                    starts.set(metric.pid, typeof metric.startId === 'number' && Number.isFinite(metric.startId) ? metric.startId : null);
+                }
+                processStartTimes = starts;
+            }
+            roots = this.readAssociatedProcessRoots(processStartTimes);
             this.associatedProcessKinds = new Map(roots.map(root => [root.pid, root.kind]));
-            this.processTreeSnapshot = this.processTreeSampler.sample(roots.map(root => root.pid));
+            this.processTreeSnapshot = this.processTreeSampler.sample(roots.map(root => root.pid), metrics);
+            processCount = this.processTreeSnapshot.processCount;
+            this.processTreeSampling.lastError = null;
         }
-        catch {
-            this.processTreeSnapshot = null;
-            this.associatedProcessKinds.clear();
+        catch (error) {
+            this.recordProcessTreeSampleError(error, durationMs);
+            return;
         }
+        const roundedDurationMs = Math.round(durationMs * 10) / 10;
+        this.processTreeSampling.lastDurationMs = roundedDurationMs;
+        this.processTreeSampling.maxDurationMs = Math.max(this.processTreeSampling.maxDurationMs, durationMs);
+        this.processTreeSampling.lastSampleAt = Date.now();
+        this.processTreeSampling.associatedRootCount = roots.length;
+        this.processTreeSampling.processCount = processCount;
+        const sampleLog = `[IPC] process_tree_sample duration_ms=${roundedDurationMs}`
+            + ` event_loop_lag_ms=${this.eventLoopLagMs}`
+            + ` associated_roots=${roots.length}`
+            + ` process_count=${processCount}`;
+        logger.debug(sampleLog);
+        const shouldWarn = roundedDurationMs >= PROCESS_TREE_SAMPLE_WARN_MS || this.eventLoopLagMs >= EVENT_LOOP_LAG_WARN_MS;
+        if (shouldWarn && this.processTreeSampling.lastSampleAt - this.lastSampleWarningAt >= SAMPLE_WARN_LOG_INTERVAL_MS) {
+            this.lastSampleWarningAt = this.processTreeSampling.lastSampleAt;
+            logger.warn(sampleLog);
+        }
+    }
+    recordProcessTreeSampleError(error, durationMs) {
+        const message = error instanceof Error ? error.message : String(error);
+        this.processTreeSampling.lastDurationMs = Math.round(durationMs * 10) / 10;
+        this.processTreeSampling.maxDurationMs = Math.max(this.processTreeSampling.maxDurationMs, durationMs);
+        this.processTreeSampling.lastError = message;
+        logger.warn(`[IPC] process_tree_sample failed duration_ms=${this.processTreeSampling.lastDurationMs} error=${message}`);
     }
-    readAssociatedProcessRoots() {
+    readAssociatedProcessRoots(processStartTimes) {
         const roots = [];
         let files;
         try {
@@ -323,7 +564,9 @@ export class IpcServer {
                 if (!Number.isInteger(pid) || pid <= 0 || pid === process.pid)
                     continue;
                 if (record.startedAt) {
-                    const actual = getProcessStartTime(pid);
+                    const actual = processStartTimes
+                        ? processStartTimes.get(pid) ?? null
+                        : getProcessStartTime(pid);
                     if (!isSameOrOlderProcess(Number(record.startedAt), actual))
                         continue;
                 }
@@ -910,16 +1153,25 @@ export class IpcServer {
                 }
             }
             case 'evolagent.list': {
+                if (this.agentApplicationService) {
+                    return { ok: true, agents: this.agentApplicationService.list() };
+                }
                 if (!this.agentRegistry)
                     return { ok: false, error: 'EvolAgentRegistry not available' };
                 return { ok: true, agents: this.agentRegistry.list() };
             }
             case 'evolagent.show': {
-                if (!this.agentRegistry)
-                    return { ok: false, error: 'EvolAgentRegistry not available' };
                 const name = cmd.name;
                 if (!name || typeof name !== 'string')
                     return { ok: false, error: 'missing name' };
+                if (this.agentApplicationService) {
+                    const info = this.agentApplicationService.info(name);
+                    if (!info)
+                        return { ok: false, error: `Agent "${name}" not found` };
+                    return { ok: true, agent: info };
+                }
+                if (!this.agentRegistry)
+                    return { ok: false, error: 'EvolAgentRegistry not available' };
                 const agent = this.agentRegistry.get(name);
                 if (!agent)
                     return { ok: false, error: `Agent "${name}" not found` };
@@ -948,11 +1200,23 @@ export class IpcServer {
                 }
             }
             case 'evolagent.reload': {
-                if (!this.agentRegistry)
-                    return { ok: false, error: 'EvolAgentRegistry not available' };
                 const name = cmd.name;
                 if (!name || typeof name !== 'string')
                     return { ok: false, error: 'missing name' };
+                if (this.agentApplicationService) {
+                    const result = await this.agentApplicationService.reload(name, { force: cmd.force === true });
+                    if (!result.ok) {
+                        return {
+                            ok: false,
+                            ...(result.code ? { code: result.code } : {}),
+                            ...(result.busyCount === undefined ? {} : { busyCount: result.busyCount }),
+                            error: result.error,
+                        };
+                    }
+                    return { ok: true, result: `Agent "${name}" reloaded` };
+                }
+                if (!this.agentRegistry)
+                    return { ok: false, error: 'EvolAgentRegistry not available' };
                 if (!this.agentReloadExecutor)
                     return { ok: false, error: 'Agent reload coordinator not initialized' };
                 try {
@@ -970,11 +1234,17 @@ export class IpcServer {
                 }
             }
             case 'evolagent.load': {
-                if (!this.agentRegistry)
-                    return { ok: false, error: 'EvolAgentRegistry not available' };
                 const aid = cmd.aid;
                 if (!aid || typeof aid !== 'string')
                     return { ok: false, error: 'missing aid' };
+                if (this.agentApplicationService) {
+                    const result = await this.agentApplicationService.load(aid);
+                    return result.ok
+                        ? { ok: true, result: `Agent "${aid}" loaded and online` }
+                        : { ok: false, ...(result.code ? { code: result.code } : {}), error: result.error };
+                }
+                if (!this.agentRegistry)
+                    return { ok: false, error: 'EvolAgentRegistry not available' };
                 const hotLoad = globalThis.__evolcore_hotLoadAgent;
                 if (!hotLoad)
                     return { ok: false, error: 'Hot-load handler not initialized' };
@@ -987,6 +1257,12 @@ export class IpcServer {
                 }
             }
             case 'evolagent.resync': {
+                if (this.agentApplicationService) {
+                    const result = await this.agentApplicationService.resync();
+                    return result.ok
+                        ? { ok: true, results: result.results }
+                        : { ok: false, ...(result.code ? { code: result.code } : {}), error: result.error };
+                }
                 if (!this.agentRegistry)
                     return { ok: false, error: 'EvolAgentRegistry not available' };
                 const resync = globalThis.__evolcore_resyncAgents;
@@ -1016,10 +1292,27 @@ export class IpcServer {
                     return { ok: false, error: 'menu.exec not configured' };
                 }
                 try {
+                    const suppliedAuth = cmd.auth && typeof cmd.auth === 'object' && !Array.isArray(cmd.auth)
+                        ? cmd.auth
+                        : undefined;
+                    const actorAid = typeof suppliedAuth?.actorAid === 'string' && suppliedAuth.actorAid.trim()
+                        ? suppliedAuth.actorAid.trim()
+                        : null;
                     const response = await this.menuExecutor(cmd.payload, {
                         source: 'ecweb',
-                        actorAid: null,
-                        localDirect: true,
+                        // The ECWeb process resolved this actor from its bearer token. The
+                        // IPC control-token gate authenticates the local ECWeb process; the
+                        // menu handler still checks that actorAid remains a configured owner.
+                        actorAid,
+                        localDirect: suppliedAuth?.localDirect === true,
+                        // Reaching this handler means the control token gate succeeded.
+                        // Never trust an authenticated flag supplied by the caller.
+                        authenticated: true,
+                        // Reaching this handler means the ECWeb control token gate
+                        // succeeded. ECWeb management is daemon-owner-authorized; the
+                        // menu layer independently revalidates remote actorAid against
+                        // the current daemon owners before applying that authority.
+                        canApprovePersistentFullAccess: true,
                     });
                     const timedResponse = withMenuProcessingTime(response, { receivedAtMono });
                     logMenuRequestCompleted(request, timedResponse, flowContext, { delivery: 'returned' });
@@ -1087,6 +1380,13 @@ export class IpcServer {
                             memory: mem,
                         },
                         processTree: processTreeDetails,
+                        sampling: {
+                            cpuIntervalMs: CPU_SAMPLE_INTERVAL_MS,
+                            processTreeIntervalMs: PROCESS_TREE_SAMPLE_INTERVAL_MS,
+                            eventLoopLagMs: this.eventLoopLagMs,
+                            maxEventLoopLagMs: this.maxEventLoopLagMs,
+                            processTree: { ...this.processTreeSampling },
+                        },
                         // 系统级：整机
                         system: {
                             ...systemMemory,
@@ -1125,6 +1425,30 @@ export class IpcServer {
  */
 /** Pass `null` as timeoutMs to wait without a client-side deadline. */
 export function ipcQuery(socketPath, cmd, timeoutMs = 3000) {
+    let socketCandidates = [socketPath];
+    if (isNamedPipe(socketPath)) {
+        const paths = resolvePaths();
+        if (socketPath === paths.socket)
+            socketCandidates = getWindowsInstanceSocketPathCandidates(paths.root);
+    }
+    if (socketCandidates.length <= 1)
+        return ipcQueryOnce(socketPath, cmd, timeoutMs);
+    return (async () => {
+        const startedAt = Date.now();
+        for (const candidate of socketCandidates) {
+            const remainingTimeout = timeoutMs === null
+                ? null
+                : Math.max(0, timeoutMs - (Date.now() - startedAt));
+            if (remainingTimeout === 0)
+                return null;
+            const response = await ipcQueryOnce(candidate, cmd, remainingTimeout);
+            if (response !== null)
+                return response;
+        }
+        return null;
+    })();
+}
+function ipcQueryOnce(socketPath, cmd, timeoutMs = 3000) {
     let authenticatedCmd = cmd;
     if (!process.env.EVOLCORE_SESSION_ID
         && requiresLocalControlToken(cmd)
@@ -1142,35 +1466,61 @@ export function ipcQuery(socketPath, cmd, timeoutMs = 3000) {
         : undefined;
     const request = delegationCommandHash ? { ...authenticatedCmd, delegationCommandHash } : authenticatedCmd;
     return new Promise((resolve) => {
+        const startedAtMono = performance.now();
+        const queryId = nextIpcQueryId(request);
+        const commandType = ipcLogToken(request.type);
+        const elapsedMs = () => Math.round(performance.now() - startedAtMono);
+        const logPhase = (phase, details = '') => {
+            logger.debug(`[IPC] query=${queryId} phase=${phase} type=${commandType} elapsed_ms=${elapsedMs()}${details}`);
+        };
         const conn = net.connect(socketPath);
         let buf = '';
+        let settled = false;
         const timer = timeoutMs === null
             ? undefined
             : setTimeout(() => {
+                if (settled)
+                    return;
+                settled = true;
+                logPhase('timeout', ` timeout_ms=${timeoutMs}`);
                 conn.destroy();
                 resolve(null);
             }, timeoutMs);
         conn.on('connect', () => {
+            if (settled)
+                return;
+            logPhase('connect');
             conn.write(JSON.stringify(request) + '\n');
         });
         conn.on('data', (data) => {
+            if (settled)
+                return;
             buf += data.toString();
             const idx = buf.indexOf('\n');
             if (idx !== -1) {
+                settled = true;
                 if (timer)
                     clearTimeout(timer);
+                let response = null;
+                let parse = 'ok';
                 try {
-                    resolve(JSON.parse(buf.slice(0, idx)));
+                    response = JSON.parse(buf.slice(0, idx));
                 }
                 catch {
-                    resolve(null);
+                    parse = 'invalid_json';
                 }
+                logPhase('response', ` bytes=${idx + 1} parse=${parse}`);
+                resolve(response);
                 conn.destroy();
             }
         });
-        conn.on('error', () => {
+        conn.on('error', (error) => {
+            if (settled)
+                return;
+            settled = true;
             if (timer)
                 clearTimeout(timer);
+            logPhase('error', ` code=${error.code ?? 'unknown'}`);
             resolve(null);
         });
     });