@livedesk/client 0.1.122 → 0.1.124

package/bin/livedesk-client-node.js

@@ -1,1566 +1,1745 @@
-#!/usr/bin/env node
-
-import net from 'net';
-import os from 'os';
-import path from 'path';
-import crypto from 'crypto';
-import { promises as fs, statfsSync } from 'fs';
-import { spawn } from 'child_process';
-
-const AGENT_VERSION = '0.1.24-livedesk.1';
-const DEFAULT_MANAGER = '127.0.0.1:5197';
-const DEFAULT_HEARTBEAT_MS = 5000;
-const DEFAULT_RECONNECT_MS = 5000;
-const EXIT_INVALID_PAIR_TOKEN = 23;
-const DEFAULT_AI_MODEL = 'gpt-5.4-mini';
-const DEFAULT_LIVE_FPS = 30;
-const MAX_LIVE_FPS = 30;
-const MAX_FRAME_BASE64_CHARS = 3 * 1024 * 1024;
-const MAX_AI_OUTPUT_CHARS = 6000;
-const MAX_FILE_TRANSFER_FILES = 24;
+#!/usr/bin/env node
+
+import net from 'net';
+import os from 'os';
+import path from 'path';
+import crypto from 'crypto';
+import { promises as fs, statfsSync } from 'fs';
+import { spawn } from 'child_process';
+
+const AGENT_VERSION = '0.1.24-livedesk.1';
+const DEFAULT_MANAGER = '127.0.0.1:5197';
+const DEFAULT_HEARTBEAT_MS = 5000;
+const DEFAULT_RECONNECT_MS = 5000;
+const EXIT_INVALID_PAIR_TOKEN = 23;
+const DEFAULT_AI_MODEL = 'gpt-5.4-mini';
+const DEFAULT_LIVE_FPS = 30;
+const MAX_LIVE_FPS = 30;
+const MAX_FRAME_BASE64_CHARS = 3 * 1024 * 1024;
+const MAX_AI_OUTPUT_CHARS = 6000;
+const MAX_FILE_TRANSFER_FILES = 24;
 const MAX_FILE_TRANSFER_BYTES = 24 * 1024 * 1024;
 const MAX_AGENT_OUTPUT_CHARS = 32000;
-
-function printHelp() {
-    console.log(`
-LiveDesk Client
-
-Usage:
-  npx @livedesk/client connect --manager 127.0.0.1:5197 --pair <token>
-
-Options:
-  --manager <host:port>  LiveDesk Hub address. Default: ${DEFAULT_MANAGER}
-  --pair <token>         LiveDesk Hub pairing token. Can also use LIVEDESK_CLIENT_PAIR_TOKEN.
-  --slot <number>        Screen wall slot number for this computer.
-  --name <name>          Friendly device name. Default: OS hostname.
-  --heartbeat <ms>       Status heartbeat interval. Default: ${DEFAULT_HEARTBEAT_MS}
-  --device-id <id>       Stable device id. Default: generated and saved per OS user.
-  --thumbnail            Enable thumbnail capture when supported. Default on Windows.
-  --no-thumbnail         Disable thumbnail capture capability.
-  --live                 Enable focused live screen streaming. Default on.
-  --no-live              Disable focused live screen streaming.
-  --tasks                Enable safe remote task inbox. Default on.
-  --no-tasks             Disable remote task dispatch capability.
-  --files-dir <path>     Default folder for received files. Default: ~/Desktop/LiveDeskFiles.
-  --ai                   Enable OpenAI-backed remote AI assist tasks.
-  --no-ai                Disable OpenAI-backed remote AI assist tasks.
-  --ai-model <model>     OpenAI model for AI assist. Default: ${DEFAULT_AI_MODEL}
-  --fake-ai              Use deterministic AI assist responses for smoke tests.
-  --fake-thumbnail       Use generated thumbnail frames for smoke tests.
-  --exit-on-disconnect   Exit after Hub disconnect. Useful for tests.
-  --exit-on-invalid-pair Exit when the Hub rejects the pair token.
-  --once                 Connect, send one status packet, and exit after welcome.
-  --version              Show the agent version.
-  --help                 Show this help.
-`.trim());
-}
-
-function isTruthy(value) {
-    return /^(1|true|yes|on)$/i.test(String(value || '').trim());
-}
-
-function isFalsy(value) {
-    return /^(0|false|no|off)$/i.test(String(value || '').trim());
-}
-
-function isNativeDesktopCaptureEnabledByDefault() {
-    const platform = os.platform();
-    const arch = os.arch();
-    if (platform === 'win32' || platform === 'darwin') {
-        return true;
-    }
-    if (platform === 'linux') {
-        return ['x64', 'arm64', 'loong64'].includes(arch);
-    }
-    return false;
-}
-
-function parseArgs(argv) {
-    const defaultDesktopCaptureEnabled = isNativeDesktopCaptureEnabledByDefault();
-    const result = {
-        command: 'connect',
-        manager: process.env.LIVEDESK_CLIENT_MANAGER || process.env.MINDEXEC_REMOTE_MANAGER || DEFAULT_MANAGER,
-        pair: process.env.LIVEDESK_CLIENT_PAIR_TOKEN || process.env.MINDEXEC_REMOTE_PAIR_TOKEN || '',
-        slotNumber: normalizeSlotNumber(process.env.LIVEDESK_CLIENT_SLOT || process.env.MINDEXEC_REMOTE_SLOT),
-        name: process.env.LIVEDESK_CLIENT_NAME || process.env.MINDEXEC_REMOTE_NAME || os.hostname(),
-        heartbeatMs: DEFAULT_HEARTBEAT_MS,
-        deviceId: '',
-        thumbnailEnabled: defaultDesktopCaptureEnabled && !isFalsy(process.env.LIVEDESK_CLIENT_THUMBNAIL ?? process.env.MINDEXEC_REMOTE_THUMBNAIL),
-        liveEnabled: defaultDesktopCaptureEnabled && !isFalsy(process.env.LIVEDESK_CLIENT_LIVE ?? process.env.MINDEXEC_REMOTE_LIVE),
-        taskEnabled: !isFalsy(process.env.LIVEDESK_CLIENT_TASKS ?? process.env.MINDEXEC_REMOTE_TASKS),
-        filesDir: process.env.LIVEDESK_CLIENT_FILES_DIR || process.env.MINDEXEC_REMOTE_FILES_DIR || '',
-        aiEnabled: isTruthy(process.env.LIVEDESK_CLIENT_AI || process.env.MINDEXEC_REMOTE_AI),
-        aiModel: process.env.LIVEDESK_CLIENT_AI_MODEL || process.env.MINDEXEC_REMOTE_AI_MODEL || process.env.OPENAI_MODEL || DEFAULT_AI_MODEL,
-        openAiApiKey: process.env.OPENAI_API_KEY || '',
-        fakeAi: isTruthy(process.env.LIVEDESK_CLIENT_FAKE_AI || process.env.MINDEXEC_REMOTE_FAKE_AI),
-        fakeThumbnail: isTruthy(process.env.LIVEDESK_CLIENT_FAKE_THUMBNAIL || process.env.MINDEXEC_REMOTE_FAKE_THUMBNAIL),
-        exitOnDisconnect: false,
-        exitOnInvalidPair: false,
-        once: false,
-        version: false,
-        help: false
-    };
-
-    const args = [...argv];
-    if (args[0] && !args[0].startsWith('-')) {
-        result.command = args.shift();
-    }
-
-    for (let index = 0; index < args.length; index += 1) {
-        const arg = args[index];
-        switch (arg) {
-            case '--manager':
-                result.manager = args[++index] || result.manager;
-                break;
-            case '--pair':
-                result.pair = args[++index] || '';
-                break;
-            case '--slot':
-                result.slotNumber = normalizeSlotNumber(args[++index] || result.slotNumber);
-                break;
-            case '--name':
-                result.name = args[++index] || result.name;
-                break;
-            case '--heartbeat':
-                result.heartbeatMs = Number(args[++index] || DEFAULT_HEARTBEAT_MS);
-                break;
-            case '--device-id':
-                result.deviceId = args[++index] || '';
-                break;
-            case '--thumbnail':
-                result.thumbnailEnabled = true;
-                break;
-            case '--no-thumbnail':
-                result.thumbnailEnabled = false;
-                break;
-            case '--live':
-                result.liveEnabled = true;
-                break;
-            case '--no-live':
-                result.liveEnabled = false;
-                break;
-            case '--tasks':
-                result.taskEnabled = true;
-                break;
-            case '--no-tasks':
-                result.taskEnabled = false;
-                break;
-            case '--files-dir':
-                result.filesDir = args[++index] || result.filesDir;
-                break;
-            case '--ai':
-                result.aiEnabled = true;
-                result.taskEnabled = true;
-                break;
-            case '--no-ai':
-                result.aiEnabled = false;
-                break;
-            case '--ai-model':
-                result.aiModel = args[++index] || result.aiModel;
-                break;
-            case '--fake-ai':
-                result.fakeAi = true;
-                result.aiEnabled = true;
-                result.taskEnabled = true;
-                break;
-            case '--fake-thumbnail':
-                result.fakeThumbnail = true;
-                result.thumbnailEnabled = true;
-                break;
-            case '--exit-on-disconnect':
-                result.exitOnDisconnect = true;
-                break;
-            case '--exit-on-invalid-pair':
-                result.exitOnInvalidPair = true;
-                break;
-            case '--once':
-                result.once = true;
-                break;
-            case '--help':
-            case '-h':
-                result.help = true;
-                break;
-            case '--version':
-            case '-v':
-                result.version = true;
-                break;
-            default:
-                throw new Error(`Unknown option: ${arg}`);
-        }
-    }
-
-    if (!Number.isFinite(result.heartbeatMs) || result.heartbeatMs < 1000) {
-        result.heartbeatMs = DEFAULT_HEARTBEAT_MS;
-    }
-
-    return result;
-}
-
-function parseManagerAddress(value) {
-    let text = String(value || DEFAULT_MANAGER).trim();
-    text = text.replace(/^tcp:\/\//i, '');
-    const separator = text.lastIndexOf(':');
-    if (separator <= 0) {
-        return {
-            host: text || '127.0.0.1',
-            port: 5197
-        };
-    }
-
-    const host = text.slice(0, separator).trim() || '127.0.0.1';
-    const port = Number(text.slice(separator + 1));
-    return {
-        host,
-        port: Number.isFinite(port) ? port : 5197
-    };
-}
-
-function normalizeDeviceId(value) {
-    return String(value || '').trim().replace(/[^a-zA-Z0-9_.:-]/g, '-').slice(0, 128);
-}
-
-function normalizeSlotNumber(value) {
-    const number = Number(String(value || '').trim());
-    return Number.isInteger(number) && number >= 1 && number <= 999 ? number : 0;
-}
-
-async function getDeviceId(explicitDeviceId = '') {
-    const explicit = normalizeDeviceId(explicitDeviceId);
-    if (explicit) {
-        return explicit;
-    }
-
-    const stateDir = path.join(os.homedir(), '.livedesk-client');
-    const statePath = path.join(stateDir, 'device.json');
-    try {
-        const state = JSON.parse(await fs.readFile(statePath, 'utf8'));
-        const existing = normalizeDeviceId(state.deviceId);
-        if (existing) {
-            return existing;
-        }
-    } catch {
-        // Create a new device id below.
-    }
-
-    const deviceId = `livedesk-${crypto.randomUUID()}`;
-    await fs.mkdir(stateDir, { recursive: true });
-    await fs.writeFile(statePath, JSON.stringify({
-        deviceId,
-        createdAt: new Date().toISOString()
-    }, null, 2));
-    return deviceId;
-}
-
-function getRootDiskStatus() {
-    const root = path.parse(os.homedir()).root || '/';
-    try {
-        const stats = statfsSync(root);
-        const totalBytes = Number(stats.blocks) * Number(stats.bsize);
-        const freeBytes = Number(stats.bavail) * Number(stats.bsize);
-        return {
-            root,
-            totalBytes,
-            freeBytes,
-            usedRatio: totalBytes > 0 ? Number(((totalBytes - freeBytes) / totalBytes).toFixed(4)) : 0
-        };
-    } catch {
-        return { root, totalBytes: 0, freeBytes: 0, usedRatio: 0 };
-    }
-}
-
-function optionalNumber(value) {
-    const number = Number(value);
-    return Number.isFinite(number) ? number : undefined;
-}
-
-function optionalRatio(value) {
-    const number = optionalNumber(value);
-    if (number === undefined) {
-        return undefined;
-    }
-    return Math.max(0, Math.min(1, number > 1 ? number / 100 : number));
-}
-
-function getAcceleratorStatus() {
-    return {
-        gpu: {
-            name: process.env.LIVEDESK_GPU_NAME || process.env.MINDEXEC_GPU_NAME || '',
-            usageRatio: optionalRatio(process.env.LIVEDESK_GPU_USAGE_RATIO || process.env.MINDEXEC_GPU_USAGE_RATIO),
-            temperatureC: optionalNumber(process.env.LIVEDESK_GPU_TEMPERATURE_C || process.env.MINDEXEC_GPU_TEMPERATURE_C)
-        },
-        npu: {
-            name: process.env.LIVEDESK_NPU_NAME || process.env.MINDEXEC_NPU_NAME || '',
-            usageRatio: optionalRatio(process.env.LIVEDESK_NPU_USAGE_RATIO || process.env.MINDEXEC_NPU_USAGE_RATIO),
-            tops: optionalNumber(process.env.LIVEDESK_NPU_TOPS || process.env.MINDEXEC_NPU_TOPS)
-        }
-    };
-}
-
-function getNetworkStatus() {
-    const interfaces = os.networkInterfaces();
-    const activeName = Object.entries(interfaces).find(([, addresses]) =>
-        Array.isArray(addresses) && addresses.some(address => !address.internal && address.family === 'IPv4')
-    )?.[0] || '';
-    return {
-        interface: activeName,
-        link: activeName || '',
-        rxMbps: optionalNumber(process.env.LIVEDESK_NETWORK_RX_MBPS || process.env.MINDEXEC_NETWORK_RX_MBPS),
-        txMbps: optionalNumber(process.env.LIVEDESK_NETWORK_TX_MBPS || process.env.MINDEXEC_NETWORK_TX_MBPS),
-        latencyMs: optionalNumber(process.env.LIVEDESK_NETWORK_LATENCY_MS || process.env.MINDEXEC_NETWORK_LATENCY_MS),
-        usageRatio: optionalRatio(process.env.LIVEDESK_NETWORK_USAGE_RATIO || process.env.MINDEXEC_NETWORK_USAGE_RATIO)
-    };
-}
-
-function getStatus(options = {}) {
-    const totalMem = os.totalmem();
-    const freeMem = os.freemem();
-    const cpus = os.cpus();
-    const loadavg = os.loadavg();
-    const cpuCores = Math.max(1, cpus.length || os.availableParallelism?.() || 1);
-    const cpuUsageRatio = loadavg[0] > 0
-        ? Number(Math.min(1, loadavg[0] / cpuCores).toFixed(4))
-        : 0;
-    const usedMemRatio = totalMem > 0 ? Number(((totalMem - freeMem) / totalMem).toFixed(4)) : 0;
-    const acceleratorStatus = getAcceleratorStatus();
-    const status = {
-        uptimeSec: Math.round(os.uptime()),
-        loadavg,
-        totalMem,
-        freeMem,
-        usedMemRatio,
-        platform: os.platform(),
-        release: os.release(),
-        role: options.aiEnabled ? 'Agent worker' : options.taskEnabled ? 'Task worker' : 'Local machine',
-        cpu: {
-            cores: cpuCores,
-            model: cpus[0]?.model || '',
-            speedMHz: cpus[0]?.speed || 0,
-            usageRatio: cpuUsageRatio,
-            load1: loadavg[0] || 0
-        },
-        memory: {
-            totalBytes: totalMem,
-            freeBytes: freeMem,
-            usedRatio: usedMemRatio
-        },
-        screenCount: 1,
-        monitorCount: 1,
-        screens: {
-            count: 1,
-            displays: []
-        },
-        disk: getRootDiskStatus(),
-        gpu: acceleratorStatus.gpu,
-        npu: acceleratorStatus.npu,
-        network: getNetworkStatus(),
-        workload: {
-            role: options.aiEnabled ? 'Agent worker' : options.taskEnabled ? 'Task worker' : 'Local machine',
-            status: 'idle',
-            title: 'idle'
-        },
-        timestamp: new Date().toISOString()
-    };
-    if (options.slotNumber) {
-        status.slotNumber = options.slotNumber;
-    }
-    return status;
-}
-
-function writeJsonLine(socket, payload) {
-    if (!socket || socket.destroyed) {
-        return false;
-    }
-
-    socket.write(`${JSON.stringify(payload)}\n`);
-    return true;
-}
-
+const launchedProcessRegistry = new Map();
+
+function printHelp() {
+    console.log(`
+LiveDesk Client
+
+Usage:
+  npx @livedesk/client connect --manager 127.0.0.1:5197 --pair <token>
+
+Options:
+  --manager <host:port>  LiveDesk Hub address. Default: ${DEFAULT_MANAGER}
+  --pair <token>         LiveDesk Hub pairing token. Can also use LIVEDESK_CLIENT_PAIR_TOKEN.
+  --slot <number>        Screen wall slot number for this computer.
+  --name <name>          Friendly device name. Default: OS hostname.
+  --heartbeat <ms>       Status heartbeat interval. Default: ${DEFAULT_HEARTBEAT_MS}
+  --device-id <id>       Stable device id. Default: generated and saved per OS user.
+  --thumbnail            Enable thumbnail capture when supported. Default on Windows.
+  --no-thumbnail         Disable thumbnail capture capability.
+  --live                 Enable focused live screen streaming. Default on.
+  --no-live              Disable focused live screen streaming.
+  --tasks                Enable safe remote task inbox. Default on.
+  --no-tasks             Disable remote task dispatch capability.
+  --files-dir <path>     Default folder for received files. Default: ~/Desktop/LiveDeskFiles.
+  --ai                   Enable OpenAI-backed remote AI assist tasks.
+  --no-ai                Disable OpenAI-backed remote AI assist tasks.
+  --ai-model <model>     OpenAI model for AI assist. Default: ${DEFAULT_AI_MODEL}
+  --fake-ai              Use deterministic AI assist responses for smoke tests.
+  --fake-thumbnail       Use generated thumbnail frames for smoke tests.
+  --exit-on-disconnect   Exit after Hub disconnect. Useful for tests.
+  --exit-on-invalid-pair Exit when the Hub rejects the pair token.
+  --once                 Connect, send one status packet, and exit after welcome.
+  --version              Show the agent version.
+  --help                 Show this help.
+`.trim());
+}
+
+function isTruthy(value) {
+    return /^(1|true|yes|on)$/i.test(String(value || '').trim());
+}
+
+function isFalsy(value) {
+    return /^(0|false|no|off)$/i.test(String(value || '').trim());
+}
+
+function isNativeDesktopCaptureEnabledByDefault() {
+    const platform = os.platform();
+    const arch = os.arch();
+    if (platform === 'win32' || platform === 'darwin') {
+        return true;
+    }
+    if (platform === 'linux') {
+        return ['x64', 'arm64', 'loong64'].includes(arch);
+    }
+    return false;
+}
+
+function parseArgs(argv) {
+    const defaultDesktopCaptureEnabled = isNativeDesktopCaptureEnabledByDefault();
+    const result = {
+        command: 'connect',
+        manager: process.env.LIVEDESK_CLIENT_MANAGER || process.env.MINDEXEC_REMOTE_MANAGER || DEFAULT_MANAGER,
+        pair: process.env.LIVEDESK_CLIENT_PAIR_TOKEN || process.env.MINDEXEC_REMOTE_PAIR_TOKEN || '',
+        slotNumber: normalizeSlotNumber(process.env.LIVEDESK_CLIENT_SLOT || process.env.MINDEXEC_REMOTE_SLOT),
+        name: process.env.LIVEDESK_CLIENT_NAME || process.env.MINDEXEC_REMOTE_NAME || os.hostname(),
+        heartbeatMs: DEFAULT_HEARTBEAT_MS,
+        deviceId: '',
+        thumbnailEnabled: defaultDesktopCaptureEnabled && !isFalsy(process.env.LIVEDESK_CLIENT_THUMBNAIL ?? process.env.MINDEXEC_REMOTE_THUMBNAIL),
+        liveEnabled: defaultDesktopCaptureEnabled && !isFalsy(process.env.LIVEDESK_CLIENT_LIVE ?? process.env.MINDEXEC_REMOTE_LIVE),
+        taskEnabled: !isFalsy(process.env.LIVEDESK_CLIENT_TASKS ?? process.env.MINDEXEC_REMOTE_TASKS),
+        filesDir: process.env.LIVEDESK_CLIENT_FILES_DIR || process.env.MINDEXEC_REMOTE_FILES_DIR || '',
+        aiEnabled: isTruthy(process.env.LIVEDESK_CLIENT_AI || process.env.MINDEXEC_REMOTE_AI),
+        aiModel: process.env.LIVEDESK_CLIENT_AI_MODEL || process.env.MINDEXEC_REMOTE_AI_MODEL || process.env.OPENAI_MODEL || DEFAULT_AI_MODEL,
+        openAiApiKey: process.env.OPENAI_API_KEY || '',
+        fakeAi: isTruthy(process.env.LIVEDESK_CLIENT_FAKE_AI || process.env.MINDEXEC_REMOTE_FAKE_AI),
+        fakeThumbnail: isTruthy(process.env.LIVEDESK_CLIENT_FAKE_THUMBNAIL || process.env.MINDEXEC_REMOTE_FAKE_THUMBNAIL),
+        exitOnDisconnect: false,
+        exitOnInvalidPair: false,
+        once: false,
+        version: false,
+        help: false
+    };
+
+    const args = [...argv];
+    if (args[0] && !args[0].startsWith('-')) {
+        result.command = args.shift();
+    }
+
+    for (let index = 0; index < args.length; index += 1) {
+        const arg = args[index];
+        switch (arg) {
+            case '--manager':
+                result.manager = args[++index] || result.manager;
+                break;
+            case '--pair':
+                result.pair = args[++index] || '';
+                break;
+            case '--slot':
+                result.slotNumber = normalizeSlotNumber(args[++index] || result.slotNumber);
+                break;
+            case '--name':
+                result.name = args[++index] || result.name;
+                break;
+            case '--heartbeat':
+                result.heartbeatMs = Number(args[++index] || DEFAULT_HEARTBEAT_MS);
+                break;
+            case '--device-id':
+                result.deviceId = args[++index] || '';
+                break;
+            case '--thumbnail':
+                result.thumbnailEnabled = true;
+                break;
+            case '--no-thumbnail':
+                result.thumbnailEnabled = false;
+                break;
+            case '--live':
+                result.liveEnabled = true;
+                break;
+            case '--no-live':
+                result.liveEnabled = false;
+                break;
+            case '--tasks':
+                result.taskEnabled = true;
+                break;
+            case '--no-tasks':
+                result.taskEnabled = false;
+                break;
+            case '--files-dir':
+                result.filesDir = args[++index] || result.filesDir;
+                break;
+            case '--ai':
+                result.aiEnabled = true;
+                result.taskEnabled = true;
+                break;
+            case '--no-ai':
+                result.aiEnabled = false;
+                break;
+            case '--ai-model':
+                result.aiModel = args[++index] || result.aiModel;
+                break;
+            case '--fake-ai':
+                result.fakeAi = true;
+                result.aiEnabled = true;
+                result.taskEnabled = true;
+                break;
+            case '--fake-thumbnail':
+                result.fakeThumbnail = true;
+                result.thumbnailEnabled = true;
+                break;
+            case '--exit-on-disconnect':
+                result.exitOnDisconnect = true;
+                break;
+            case '--exit-on-invalid-pair':
+                result.exitOnInvalidPair = true;
+                break;
+            case '--once':
+                result.once = true;
+                break;
+            case '--help':
+            case '-h':
+                result.help = true;
+                break;
+            case '--version':
+            case '-v':
+                result.version = true;
+                break;
+            default:
+                throw new Error(`Unknown option: ${arg}`);
+        }
+    }
+
+    if (!Number.isFinite(result.heartbeatMs) || result.heartbeatMs < 1000) {
+        result.heartbeatMs = DEFAULT_HEARTBEAT_MS;
+    }
+
+    return result;
+}
+
+function parseManagerAddress(value) {
+    let text = String(value || DEFAULT_MANAGER).trim();
+    text = text.replace(/^tcp:\/\//i, '');
+    const separator = text.lastIndexOf(':');
+    if (separator <= 0) {
+        return {
+            host: text || '127.0.0.1',
+            port: 5197
+        };
+    }
+
+    const host = text.slice(0, separator).trim() || '127.0.0.1';
+    const port = Number(text.slice(separator + 1));
+    return {
+        host,
+        port: Number.isFinite(port) ? port : 5197
+    };
+}
+
+function normalizeDeviceId(value) {
+    return String(value || '').trim().replace(/[^a-zA-Z0-9_.:-]/g, '-').slice(0, 128);
+}
+
+function normalizeSlotNumber(value) {
+    const number = Number(String(value || '').trim());
+    return Number.isInteger(number) && number >= 1 && number <= 999 ? number : 0;
+}
+
+async function getDeviceId(explicitDeviceId = '') {
+    const explicit = normalizeDeviceId(explicitDeviceId);
+    if (explicit) {
+        return explicit;
+    }
+
+    const stateDir = path.join(os.homedir(), '.livedesk-client');
+    const statePath = path.join(stateDir, 'device.json');
+    try {
+        const state = JSON.parse(await fs.readFile(statePath, 'utf8'));
+        const existing = normalizeDeviceId(state.deviceId);
+        if (existing) {
+            return existing;
+        }
+    } catch {
+        // Create a new device id below.
+    }
+
+    const deviceId = `livedesk-${crypto.randomUUID()}`;
+    await fs.mkdir(stateDir, { recursive: true });
+    await fs.writeFile(statePath, JSON.stringify({
+        deviceId,
+        createdAt: new Date().toISOString()
+    }, null, 2));
+    return deviceId;
+}
+
+function getRootDiskStatus() {
+    const root = path.parse(os.homedir()).root || '/';
+    try {
+        const stats = statfsSync(root);
+        const totalBytes = Number(stats.blocks) * Number(stats.bsize);
+        const freeBytes = Number(stats.bavail) * Number(stats.bsize);
+        return {
+            root,
+            totalBytes,
+            freeBytes,
+            usedRatio: totalBytes > 0 ? Number(((totalBytes - freeBytes) / totalBytes).toFixed(4)) : 0
+        };
+    } catch {
+        return { root, totalBytes: 0, freeBytes: 0, usedRatio: 0 };
+    }
+}
+
+function optionalNumber(value) {
+    const number = Number(value);
+    return Number.isFinite(number) ? number : undefined;
+}
+
+function optionalRatio(value) {
+    const number = optionalNumber(value);
+    if (number === undefined) {
+        return undefined;
+    }
+    return Math.max(0, Math.min(1, number > 1 ? number / 100 : number));
+}
+
+function getAcceleratorStatus() {
+    return {
+        gpu: {
+            name: process.env.LIVEDESK_GPU_NAME || process.env.MINDEXEC_GPU_NAME || '',
+            usageRatio: optionalRatio(process.env.LIVEDESK_GPU_USAGE_RATIO || process.env.MINDEXEC_GPU_USAGE_RATIO),
+            temperatureC: optionalNumber(process.env.LIVEDESK_GPU_TEMPERATURE_C || process.env.MINDEXEC_GPU_TEMPERATURE_C)
+        },
+        npu: {
+            name: process.env.LIVEDESK_NPU_NAME || process.env.MINDEXEC_NPU_NAME || '',
+            usageRatio: optionalRatio(process.env.LIVEDESK_NPU_USAGE_RATIO || process.env.MINDEXEC_NPU_USAGE_RATIO),
+            tops: optionalNumber(process.env.LIVEDESK_NPU_TOPS || process.env.MINDEXEC_NPU_TOPS)
+        }
+    };
+}
+
+function getNetworkStatus() {
+    const interfaces = os.networkInterfaces();
+    const activeName = Object.entries(interfaces).find(([, addresses]) =>
+        Array.isArray(addresses) && addresses.some(address => !address.internal && address.family === 'IPv4')
+    )?.[0] || '';
+    return {
+        interface: activeName,
+        link: activeName || '',
+        rxMbps: optionalNumber(process.env.LIVEDESK_NETWORK_RX_MBPS || process.env.MINDEXEC_NETWORK_RX_MBPS),
+        txMbps: optionalNumber(process.env.LIVEDESK_NETWORK_TX_MBPS || process.env.MINDEXEC_NETWORK_TX_MBPS),
+        latencyMs: optionalNumber(process.env.LIVEDESK_NETWORK_LATENCY_MS || process.env.MINDEXEC_NETWORK_LATENCY_MS),
+        usageRatio: optionalRatio(process.env.LIVEDESK_NETWORK_USAGE_RATIO || process.env.MINDEXEC_NETWORK_USAGE_RATIO)
+    };
+}
+
+function getStatus(options = {}) {
+    const totalMem = os.totalmem();
+    const freeMem = os.freemem();
+    const cpus = os.cpus();
+    const loadavg = os.loadavg();
+    const cpuCores = Math.max(1, cpus.length || os.availableParallelism?.() || 1);
+    const cpuUsageRatio = loadavg[0] > 0
+        ? Number(Math.min(1, loadavg[0] / cpuCores).toFixed(4))
+        : 0;
+    const usedMemRatio = totalMem > 0 ? Number(((totalMem - freeMem) / totalMem).toFixed(4)) : 0;
+    const acceleratorStatus = getAcceleratorStatus();
+    const status = {
+        uptimeSec: Math.round(os.uptime()),
+        loadavg,
+        totalMem,
+        freeMem,
+        usedMemRatio,
+        platform: os.platform(),
+        release: os.release(),
+        role: options.aiEnabled ? 'Agent worker' : options.taskEnabled ? 'Task worker' : 'Local machine',
+        cpu: {
+            cores: cpuCores,
+            model: cpus[0]?.model || '',
+            speedMHz: cpus[0]?.speed || 0,
+            usageRatio: cpuUsageRatio,
+            load1: loadavg[0] || 0
+        },
+        memory: {
+            totalBytes: totalMem,
+            freeBytes: freeMem,
+            usedRatio: usedMemRatio
+        },
+        screenCount: 1,
+        monitorCount: 1,
+        screens: {
+            count: 1,
+            displays: []
+        },
+        disk: getRootDiskStatus(),
+        gpu: acceleratorStatus.gpu,
+        npu: acceleratorStatus.npu,
+        network: getNetworkStatus(),
+        workload: {
+            role: options.aiEnabled ? 'Agent worker' : options.taskEnabled ? 'Task worker' : 'Local machine',
+            status: 'idle',
+            title: 'idle'
+        },
+        timestamp: new Date().toISOString()
+    };
+    if (options.slotNumber) {
+        status.slotNumber = options.slotNumber;
+    }
+    return status;
+}
+
+function writeJsonLine(socket, payload) {
+    if (!socket || socket.destroyed) {
+        return false;
+    }
+
+    socket.write(`${JSON.stringify(payload)}\n`);
+    return true;
+}
+
 function wait(ms) {
     return new Promise(resolve => setTimeout(resolve, ms));
 }
 
-function getDefaultFilesDir() {
-    return path.join(os.homedir(), 'Desktop', 'LiveDeskFiles');
-}
-
-function normalizeDirectoryPath(value, fallback = getDefaultFilesDir()) {
-    const text = String(value || '').replace(/\0/g, '').trim();
-    if (!text) {
-        return fallback;
-    }
-    if (path.isAbsolute(text)) {
-        return path.resolve(text);
-    }
-    return path.resolve(fallback, text);
-}
-
-function sanitizePathSegment(value, fallback = 'file') {
-    const text = String(value || '')
-        .replace(/\0/g, '')
-        .replace(/[<>:"|?*\x00-\x1f]/g, '_')
-        .replace(/[\\/]+/g, '_')
-        .trim();
-    const normalized = text && text !== '.' && text !== '..' ? text : fallback;
-    return normalized.slice(0, 160);
+async function waitForNodeServiceState(executable, service, expectedState, timeoutMs = 15000) {
+    const deadline = Date.now() + Math.max(1000, Math.min(30000, timeoutMs));
+    while (Date.now() < deadline) {
+        const query = process.platform === 'win32'
+            ? await runNodeAgentProcess(executable, ['query', service], 5000)
+            : await runNodeAgentProcess(executable, ['is-active', service], 5000);
+        const output = String(query.output || '').toLowerCase();
+        const reached = process.platform === 'win32'
+            ? output.includes(String(expectedState).toLowerCase())
+            : expectedState === 'running'
+                ? output.includes('active') && !output.includes('inactive')
+                : output.includes('inactive') || output.includes('dead') || output.includes('failed');
+        if (reached) return query;
+        await wait(250);
+    }
+    throw new Error(`Service ${service} did not reach ${expectedState} state in time.`);
 }
-
-function sanitizeRelativeFilePath(value, fallbackName = 'file') {
-    const parts = String(value || '')
-        .replace(/\0/g, '')
-        .split(/[\\/]+/)
-        .map(part => sanitizePathSegment(part, ''))
-        .filter(Boolean)
-        .filter(part => part !== '.' && part !== '..');
-    if (parts.length === 0) {
-        return sanitizePathSegment(fallbackName, 'file');
-    }
-    return path.join(...parts.slice(-8));
+
+function getDefaultFilesDir() {
+    return path.join(os.homedir(), 'Desktop', 'LiveDeskFiles');
+}
+
+function normalizeDirectoryPath(value, fallback = getDefaultFilesDir()) {
+    const text = String(value || '').replace(/\0/g, '').trim();
+    if (!text) {
+        return fallback;
+    }
+    if (path.isAbsolute(text)) {
+        return path.resolve(text);
+    }
+    return path.resolve(fallback, text);
+}
+
+function sanitizePathSegment(value, fallback = 'file') {
+    const text = String(value || '')
+        .replace(/\0/g, '')
+        .replace(/[<>:"|?*\x00-\x1f]/g, '_')
+        .replace(/[\\/]+/g, '_')
+        .trim();
+    const normalized = text && text !== '.' && text !== '..' ? text : fallback;
+    return normalized.slice(0, 160);
+}
+
+function sanitizeRelativeFilePath(value, fallbackName = 'file') {
+    const parts = String(value || '')
+        .replace(/\0/g, '')
+        .split(/[\\/]+/)
+        .map(part => sanitizePathSegment(part, ''))
+        .filter(Boolean)
+        .filter(part => part !== '.' && part !== '..');
+    if (parts.length === 0) {
+        return sanitizePathSegment(fallbackName, 'file');
+    }
+    return path.join(...parts.slice(-8));
+}
+
+async function handleFileTransferCommand(options, payload = {}) {
+    const files = Array.isArray(payload.files) ? payload.files.slice(0, MAX_FILE_TRANSFER_FILES) : [];
+    if (files.length === 0) {
+        throw new Error('No files were included in the transfer.');
+    }
+
+    const baseDir = normalizeDirectoryPath(payload.remoteDirectory || options.filesDir);
+    await fs.mkdir(baseDir, { recursive: true });
+
+    let totalBytes = 0;
+    const saved = [];
+    for (const file of files) {
+        const name = sanitizePathSegment(file?.name, 'file');
+        const relativePath = sanitizeRelativeFilePath(file?.relativePath || name, name);
+        const targetPath = path.resolve(baseDir, relativePath);
+        const relativeFromBase = path.relative(baseDir, targetPath);
+        if (relativeFromBase.startsWith('..') || path.isAbsolute(relativeFromBase)) {
+            throw new Error(`Unsafe file path: ${relativePath}`);
+        }
+
+        const dataBase64 = String(file?.dataBase64 || '').replace(/^data:[^,]*,/i, '').trim();
+        if (!dataBase64) {
+            throw new Error(`Missing file data: ${name}`);
+        }
+        const buffer = Buffer.from(dataBase64, 'base64');
+        totalBytes += buffer.length;
+        if (totalBytes > MAX_FILE_TRANSFER_BYTES) {
+            throw new Error('File transfer exceeded the local size limit.');
+        }
+
+        await fs.mkdir(path.dirname(targetPath), { recursive: true });
+        await fs.writeFile(targetPath, buffer);
+        saved.push({
+            name,
+            relativePath,
+            path: targetPath,
+            bytes: buffer.length
+        });
+    }
+
+    return {
+        kind: 'file.transfer',
+        transferId: String(payload.transferId || '').slice(0, 128),
+        status: 'completed',
+        directory: baseDir,
+        files: saved,
+        totalBytes,
+        completedAt: new Date().toISOString()
+    };
+}
+
+async function handleFileTransferChunkCommand(options, payload = {}) {
+    const baseDir = normalizeDirectoryPath(payload.remoteDirectory || options.filesDir);
+    const name = sanitizePathSegment(payload.name, 'file');
+    const relativePath = sanitizeRelativeFilePath(payload.relativePath || name, name);
+    const targetPath = path.resolve(baseDir, relativePath);
+    const relativeFromBase = path.relative(baseDir, targetPath);
+    if (relativeFromBase.startsWith('..') || path.isAbsolute(relativeFromBase)) {
+        throw new Error(`Unsafe file path: ${relativePath}`);
+    }
+
+    const transferId = String(payload.transferId || '').replace(/[^a-zA-Z0-9_.:-]/g, '-').slice(0, 128);
+    const offset = Math.max(0, Math.floor(Number(payload.offset) || 0));
+    const totalBytes = Math.max(0, Math.floor(Number(payload.totalBytes) || 0));
+    const final = payload.final === true;
+    const buffer = payload.dataBase64 ? Buffer.from(String(payload.dataBase64), 'base64') : Buffer.alloc(0);
+    if (!transferId || offset > totalBytes || offset + buffer.length > totalBytes || buffer.length > 512 * 1024) {
+        throw new Error('Invalid file transfer chunk.');
+    }
+    if (buffer.length === 0 && !(final && totalBytes === 0 && offset === 0)) {
+        throw new Error('Empty file chunks are not allowed.');
+    }
+
+    await fs.mkdir(path.dirname(targetPath), { recursive: true });
+    const tempPath = `${targetPath}.livedesk-${transferId}.part`;
+    const handle = await fs.open(tempPath, offset === 0 ? 'w+' : 'r+');
+    let completedSize = 0;
+    try {
+        const before = await handle.stat();
+        if (offset > before.size) {
+            throw new Error(`File chunk gap detected at ${offset}; current length is ${before.size}.`);
+        }
+        if (buffer.length > 0) {
+            await handle.write(buffer, 0, buffer.length, offset);
+        }
+        const after = await handle.stat();
+        completedSize = after.size;
+        if (final) {
+            await handle.sync();
+            if (after.size !== totalBytes) {
+                throw new Error(`File transfer is incomplete (${after.size}/${totalBytes}).`);
+            }
+        }
+    } finally {
+        await handle.close();
+    }
+
+    if (final) {
+        await fs.rm(targetPath, { force: true });
+        await fs.rename(tempPath, targetPath);
+        const lastModified = Number(payload.lastModified || 0);
+        if (lastModified > 0) {
+            const modifiedAt = new Date(lastModified);
+            await fs.utimes(targetPath, modifiedAt, modifiedAt).catch(() => undefined);
+        }
+    }
+
+    return {
+        kind: 'file.transfer.chunk',
+        transferId,
+        status: final ? 'completed' : 'receiving',
+        relativePath: relativePath.split(path.sep).join('/'),
+        offset,
+        bytes: buffer.length,
+        totalBytes,
+        completedSize,
+        final,
+        completedAt: final ? new Date().toISOString() : null
+    };
+}
+
+function clampNumber(value, min, max, fallback) {
+    const number = Number(value);
+    if (!Number.isFinite(number)) {
+        return fallback;
+    }
+
+    return Math.max(min, Math.min(max, Math.floor(number)));
+}
+
+function createFakeThumbnailFrame(options, payload, frameSeq) {
+    const width = clampNumber(payload?.maxWidth, 160, 3840, 360);
+    const height = clampNumber(payload?.maxHeight, 90, 2160, 220);
+    const now = new Date().toISOString();
+    const title = String(options.name || os.hostname()).replace(/[<>&"']/g, '_');
+    const svg = [
+        `<svg xmlns="http://www.w3.org/2000/svg" width="${width}" height="${height}" viewBox="0 0 ${width} ${height}">`,
+        '<rect width="100%" height="100%" fill="#0f172a"/>',
+        '<rect x="14" y="14" width="calc(100% - 28px)" height="calc(100% - 28px)" rx="12" fill="#1e293b" stroke="#38bdf8" stroke-width="2"/>',
+        `<text x="28" y="48" fill="#e2e8f0" font-family="Arial, sans-serif" font-size="20" font-weight="700">${title}</text>`,
+        `<text x="28" y="82" fill="#93c5fd" font-family="Arial, sans-serif" font-size="14">LiveDesk Client Thumbnail</text>`,
+        `<text x="28" y="${height - 30}" fill="#94a3b8" font-family="Consolas, monospace" font-size="12">${now}</text>`,
+        '</svg>'
+    ].join('');
+
+    return {
+        frameSeq,
+        width,
+        height,
+        sourceWidth: width,
+        sourceHeight: height,
+        mimeType: 'image/svg+xml',
+        data: Buffer.from(svg, 'utf8').toString('base64'),
+        capturedAt: now
+    };
+}
+
+function readJpegDimensions(buffer) {
+    if (!Buffer.isBuffer(buffer) || buffer.length < 4 || buffer[0] !== 0xff || buffer[1] !== 0xd8) {
+        return { width: 0, height: 0 };
+    }
+
+    let offset = 2;
+    while (offset + 9 < buffer.length) {
+        if (buffer[offset] !== 0xff) {
+            offset += 1;
+            continue;
+        }
+
+        const marker = buffer[offset + 1];
+        const blockLength = buffer.readUInt16BE(offset + 2);
+        if (blockLength < 2) {
+            break;
+        }
+
+        const isStartOfFrame = marker >= 0xc0
+            && marker <= 0xcf
+            && ![0xc4, 0xc8, 0xcc].includes(marker);
+        if (isStartOfFrame) {
+            return {
+                height: buffer.readUInt16BE(offset + 5),
+                width: buffer.readUInt16BE(offset + 7)
+            };
+        }
+
+        offset += 2 + blockLength;
+    }
+
+    return { width: 0, height: 0 };
+}
+
+function normalizeMonitorIndex(value, fallback = 0) {
+    return clampInteger(value, 0, 63, fallback);
+}
+
+async function captureNativeDesktopFrame(frameSeq, monitorIndex = 0) {
+    const screenshotModule = await import('node-screenshots');
+    const Monitor = screenshotModule.Monitor || screenshotModule.default?.Monitor;
+    if (!Monitor?.all) {
+        throw new Error('node-screenshots Monitor API is unavailable.');
+    }
+
+    const monitors = Monitor.all();
+    const selectedIndex = Math.max(0, Math.min(monitors.length - 1, normalizeMonitorIndex(monitorIndex)));
+    const monitor = monitors[selectedIndex] || monitors.find(item => item?.isPrimary?.() === true) || monitors[0];
+    if (!monitor?.captureImage) {
+        throw new Error('No capturable desktop monitor was found.');
+    }
+
+    const image = await monitor.captureImage();
+    const jpeg = await image.toJpeg();
+    const buffer = Buffer.isBuffer(jpeg) ? jpeg : Buffer.from(jpeg);
+    if (buffer.toString('base64').length > MAX_FRAME_BASE64_CHARS) {
+        throw new Error('Desktop capture exceeded the remote frame size limit.');
+    }
+
+    const dimensions = readJpegDimensions(buffer);
+    return {
+        frameSeq,
+        width: dimensions.width,
+        height: dimensions.height,
+        sourceWidth: dimensions.width,
+        sourceHeight: dimensions.height,
+        mimeType: 'image/jpeg',
+        data: buffer.toString('base64'),
+        monitorIndex: selectedIndex,
+        monitorCount: Math.max(1, monitors.length),
+        capturedAt: new Date().toISOString()
+    };
+}
+
+async function captureDesktopThumbnailFrame(payload, frameSeq) {
+    return await captureNativeDesktopFrame(frameSeq, payload?.monitorIndex ?? payload?.screenIndex ?? payload?.displayIndex);
+}
+
+async function captureScreenFrame(options, payload, frameSeq, capability = 'thumbnail') {
+    const enabled = capability === 'live' ? options.liveEnabled : options.thumbnailEnabled;
+    if (!enabled) {
+        throw new Error(`${capability} capability is disabled`);
+    }
+
+    return options.fakeThumbnail
+        ? createFakeThumbnailFrame(options, payload, frameSeq)
+        : await captureDesktopThumbnailFrame(payload, frameSeq);
+}
+
+async function captureThumbnailFrame(options, payload, frameSeq) {
+    return await captureScreenFrame(options, payload, frameSeq, 'thumbnail');
+}
+
+function normalizeApprovalLevel(value) {
+    const level = String(value || 'task-only').trim().toLowerCase();
+    return level === 'ai-assist' ? 'ai-assist' : 'task-only';
+}
+
+function buildAiPrompt(options, payload, instruction) {
+    const title = String(payload?.title || 'Remote AI task').trim();
+    return [
+        'You are the LiveDesk client AI assistant running on a controlled remote computer.',
+        'Complete the LiveDesk Hub task as a text-only assistant.',
+        'Do not claim you used shell commands, file writes, browser automation, keyboard input, or mouse input.',
+        'If the task requires external side effects, explain what would be needed and stop.',
+        '',
+        `Device: ${options.name} (${os.hostname()}, ${os.platform()} ${os.release()}, ${os.arch()})`,
+        `Task title: ${title}`,
+        '',
+        'Hub instruction:',
+        instruction
+    ].join('\n');
+}
+
+function extractResponseText(response) {
+    if (typeof response?.output_text === 'string' && response.output_text.trim()) {
+        return response.output_text.trim();
+    }
+
+    const parts = [];
+    if (Array.isArray(response?.output)) {
+        for (const item of response.output) {
+            if (!Array.isArray(item?.content)) {
+                continue;
+            }
+
+            for (const content of item.content) {
+                if (typeof content?.text === 'string') {
+                    parts.push(content.text);
+                }
+                if (typeof content?.output_text === 'string') {
+                    parts.push(content.output_text);
+                }
+            }
+        }
+    }
+
+    return parts.join('\n').trim();
+}
+
+async function runAiAssistTask(options, payload, instruction) {
+    if (!options.aiEnabled) {
+        throw new Error('AI assist capability is disabled. Start the agent with --ai to enable it.');
+    }
+
+    if (options.fakeAi) {
+        return {
+            text: [
+                `Fake AI assist completed on ${options.name}.`,
+                '',
+                `Instruction: ${instruction.slice(0, 500)}`,
+                '',
+                'No shell, file, input, browser, or persistent side effects were performed.'
+            ].join('\n'),
+            model: 'fake-ai',
+            responseId: `fake-ai-${String(payload?.taskId || crypto.randomUUID()).slice(0, 96)}`
+        };
+    }
+
+    if (!options.openAiApiKey) {
+        throw new Error('OPENAI_API_KEY is required for --ai remote tasks.');
+    }
+
+    const openaiModule = await import('openai');
+    const OpenAI = openaiModule.default || openaiModule.OpenAI;
+    const client = new OpenAI({ apiKey: options.openAiApiKey });
+    const model = String(payload?.model || options.aiModel || DEFAULT_AI_MODEL).trim() || DEFAULT_AI_MODEL;
+    const response = await client.responses.create({
+        model,
+        input: buildAiPrompt(options, payload, instruction)
+    });
+    const text = extractResponseText(response);
+    if (!text) {
+        throw new Error('AI assist returned no text output.');
+    }
+
+    return {
+        text: text.slice(0, MAX_AI_OUTPUT_CHARS),
+        model,
+        responseId: response?.id || ''
+    };
+}
+
+function clampInteger(value, min, max, fallback) {
+    const number = Number(value);
+    if (!Number.isFinite(number)) {
+        return fallback;
+    }
+
+    return Math.max(min, Math.min(max, Math.floor(number)));
+}
+
+function stopLiveStream(activeStreams, streamId = '') {
+    if (streamId) {
+        const existing = activeStreams.get(streamId);
+        if (existing?.timer) {
+            clearInterval(existing.timer);
+        }
+        activeStreams.delete(streamId);
+        return existing ? 1 : 0;
+    }
+
+    let stopped = 0;
+    for (const stream of activeStreams.values()) {
+        if (stream?.timer) {
+            clearInterval(stream.timer);
+            stopped += 1;
+        }
+    }
+    activeStreams.clear();
+    return stopped;
+}
+
+function startLiveStream(socket, options, message, nextFrameSeq, activeStreams) {
+    if (!options.liveEnabled) {
+        throw new Error('live stream capability is disabled');
+    }
+
+    const payload = message.payload || {};
+    const streamId = String(payload.streamId || `live-${Date.now()}`)
+        .replace(/[^a-zA-Z0-9_.:-]/g, '-')
+        .slice(0, 128) || `live-${Date.now()}`;
+    const fps = clampInteger(payload.fps, 1, MAX_LIVE_FPS, DEFAULT_LIVE_FPS);
+    const intervalMs = Math.max(33, Math.round(1000 / fps));
+    stopLiveStream(activeStreams, streamId);
+
+    const stream = {
+        streamId,
+        fps,
+        intervalMs,
+        inFlight: false,
+        stopped: false,
+        frameDrops: 0,
+        timer: null
+    };
+    console.log('전송모드 - mode1-jpeg (Mode 1 - Test JPEG Binary)');
+
+    const captureAndSend = async () => {
+        if (stream.stopped || stream.inFlight || socket.destroyed) {
+            if (stream.inFlight) {
+                stream.frameDrops += 1;
+            }
+            return;
+        }
+
+        stream.inFlight = true;
+        try {
+            const frame = await captureScreenFrame(options, payload, nextFrameSeq(), 'live');
+            if (String(frame.data || '').length > MAX_FRAME_BASE64_CHARS) {
+                stream.frameDrops += 1;
+                return;
+            }
+
+            const sent = writeJsonLine(socket, {
+                type: 'stream.frame',
+                commandId: message.commandId,
+                streamId,
+                frameSeq: frame.frameSeq,
+                width: frame.width,
+                height: frame.height,
+                sourceWidth: frame.sourceWidth || frame.width,
+                sourceHeight: frame.sourceHeight || frame.height,
+                mimeType: frame.mimeType,
+                capturedAt: frame.capturedAt,
+                fps,
+                mode: 'mode1-jpeg',
+                monitorIndex: frame.monitorIndex ?? 0,
+                monitorCount: frame.monitorCount ?? 1,
+                droppedByAgent: stream.frameDrops,
+                data: frame.data
+            });
+
+            if (!sent) {
+                stream.stopped = true;
+                stopLiveStream(activeStreams, streamId);
+            }
+        } catch {
+            stream.frameDrops += 1;
+        } finally {
+            stream.inFlight = false;
+        }
+    };
+
+    stream.timer = setInterval(() => {
+        captureAndSend().catch(() => {
+            stream.frameDrops += 1;
+        });
+    }, intervalMs);
+    stream.timer.unref?.();
+    activeStreams.set(streamId, stream);
+    captureAndSend().catch(() => {
+        stream.frameDrops += 1;
+    });
+    return { streamId, fps, intervalMs };
+}
+
+function isSensitiveAgentPath(value) {
+    const normalized = String(value || '').replaceAll('\\', '/').toLowerCase();
+    return normalized.includes('/.codex/') || normalized.endsWith('/auth.json') || normalized.includes('/.ssh/') || normalized.includes('/id_rsa') || normalized.endsWith('.pem') || normalized.endsWith('.key') || normalized.endsWith('/.env') || normalized.includes('/credential') || normalized.includes('/secret') || normalized.includes('/password');
 }
 
-async function handleFileTransferCommand(options, payload = {}) {
-    const files = Array.isArray(payload.files) ? payload.files.slice(0, MAX_FILE_TRANSFER_FILES) : [];
-    if (files.length === 0) {
-        throw new Error('No files were included in the transfer.');
-    }
-
-    const baseDir = normalizeDirectoryPath(payload.remoteDirectory || options.filesDir);
-    await fs.mkdir(baseDir, { recursive: true });
-
-    let totalBytes = 0;
-    const saved = [];
-    for (const file of files) {
-        const name = sanitizePathSegment(file?.name, 'file');
-        const relativePath = sanitizeRelativeFilePath(file?.relativePath || name, name);
-        const targetPath = path.resolve(baseDir, relativePath);
-        const relativeFromBase = path.relative(baseDir, targetPath);
-        if (relativeFromBase.startsWith('..') || path.isAbsolute(relativeFromBase)) {
-            throw new Error(`Unsafe file path: ${relativePath}`);
-        }
-
-        const dataBase64 = String(file?.dataBase64 || '').replace(/^data:[^,]*,/i, '').trim();
-        if (!dataBase64) {
-            throw new Error(`Missing file data: ${name}`);
-        }
-        const buffer = Buffer.from(dataBase64, 'base64');
-        totalBytes += buffer.length;
-        if (totalBytes > MAX_FILE_TRANSFER_BYTES) {
-            throw new Error('File transfer exceeded the local size limit.');
-        }
-
-        await fs.mkdir(path.dirname(targetPath), { recursive: true });
-        await fs.writeFile(targetPath, buffer);
-        saved.push({
-            name,
-            relativePath,
-            path: targetPath,
-            bytes: buffer.length
-        });
-    }
-
-    return {
-        kind: 'file.transfer',
-        transferId: String(payload.transferId || '').slice(0, 128),
-        status: 'completed',
-        directory: baseDir,
-        files: saved,
-        totalBytes,
-        completedAt: new Date().toISOString()
-    };
+function isPathWithinAgentRoot(root, candidate) {
+    const relative = path.relative(root, candidate);
+    return relative === '' || (relative !== '..' && !relative.startsWith(`..${path.sep}`) && !path.isAbsolute(relative));
 }
 
-async function handleFileTransferChunkCommand(options, payload = {}) {
-    const baseDir = normalizeDirectoryPath(payload.remoteDirectory || options.filesDir);
-    const name = sanitizePathSegment(payload.name, 'file');
-    const relativePath = sanitizeRelativeFilePath(payload.relativePath || name, name);
-    const targetPath = path.resolve(baseDir, relativePath);
-    const relativeFromBase = path.relative(baseDir, targetPath);
-    if (relativeFromBase.startsWith('..') || path.isAbsolute(relativeFromBase)) {
-        throw new Error(`Unsafe file path: ${relativePath}`);
-    }
-
-    const transferId = String(payload.transferId || '').replace(/[^a-zA-Z0-9_.:-]/g, '-').slice(0, 128);
-    const offset = Math.max(0, Math.floor(Number(payload.offset) || 0));
-    const totalBytes = Math.max(0, Math.floor(Number(payload.totalBytes) || 0));
-    const final = payload.final === true;
-    const buffer = payload.dataBase64 ? Buffer.from(String(payload.dataBase64), 'base64') : Buffer.alloc(0);
-    if (!transferId || offset > totalBytes || offset + buffer.length > totalBytes || buffer.length > 512 * 1024) {
-        throw new Error('Invalid file transfer chunk.');
-    }
-    if (buffer.length === 0 && !(final && totalBytes === 0 && offset === 0)) {
-        throw new Error('Empty file chunks are not allowed.');
-    }
-
-    await fs.mkdir(path.dirname(targetPath), { recursive: true });
-    const tempPath = `${targetPath}.livedesk-${transferId}.part`;
-    const handle = await fs.open(tempPath, offset === 0 ? 'w+' : 'r+');
-    let completedSize = 0;
-    try {
-        const before = await handle.stat();
-        if (offset > before.size) {
-            throw new Error(`File chunk gap detected at ${offset}; current length is ${before.size}.`);
-        }
-        if (buffer.length > 0) {
-            await handle.write(buffer, 0, buffer.length, offset);
-        }
-        const after = await handle.stat();
-        completedSize = after.size;
-        if (final) {
-            await handle.sync();
-            if (after.size !== totalBytes) {
-                throw new Error(`File transfer is incomplete (${after.size}/${totalBytes}).`);
+async function assertAgentPathDoesNotTraverseLink(base, resolved) {
+    await fs.mkdir(base, { recursive: true });
+    const canonicalRoot = await fs.realpath(base);
+    let current = resolved;
+    while (true) {
+        try {
+            const stat = await fs.lstat(current);
+            if (stat.isSymbolicLink()) {
+                throw new Error('Safe Agent paths cannot traverse symbolic links or junctions.');
             }
-        }
-    } finally {
-        await handle.close();
-    }
-
-    if (final) {
-        await fs.rm(targetPath, { force: true });
-        await fs.rename(tempPath, targetPath);
-        const lastModified = Number(payload.lastModified || 0);
-        if (lastModified > 0) {
-            const modifiedAt = new Date(lastModified);
-            await fs.utimes(targetPath, modifiedAt, modifiedAt).catch(() => undefined);
+            const canonicalCurrent = await fs.realpath(current);
+            if (!isPathWithinAgentRoot(canonicalRoot, canonicalCurrent)) {
+                throw new Error('Safe Agent path resolves outside the LiveDesk files directory.');
+            }
+            return;
+        } catch (error) {
+            if (error?.code !== 'ENOENT') throw error;
+            const parent = path.dirname(current);
+            if (parent === current) throw new Error('Safe Agent path could not be verified.');
+            current = parent;
         }
     }
-
-    return {
-        kind: 'file.transfer.chunk',
-        transferId,
-        status: final ? 'completed' : 'receiving',
-        relativePath: relativePath.split(path.sep).join('/'),
-        offset,
-        bytes: buffer.length,
-        totalBytes,
-        completedSize,
-        final,
-        completedAt: final ? new Date().toISOString() : null
-    };
-}
-
-function clampNumber(value, min, max, fallback) {
-    const number = Number(value);
-    if (!Number.isFinite(number)) {
-        return fallback;
-    }
-
-    return Math.max(min, Math.min(max, Math.floor(number)));
-}
-
-function createFakeThumbnailFrame(options, payload, frameSeq) {
-    const width = clampNumber(payload?.maxWidth, 160, 3840, 360);
-    const height = clampNumber(payload?.maxHeight, 90, 2160, 220);
-    const now = new Date().toISOString();
-    const title = String(options.name || os.hostname()).replace(/[<>&"']/g, '_');
-    const svg = [
-        `<svg xmlns="http://www.w3.org/2000/svg" width="${width}" height="${height}" viewBox="0 0 ${width} ${height}">`,
-        '<rect width="100%" height="100%" fill="#0f172a"/>',
-        '<rect x="14" y="14" width="calc(100% - 28px)" height="calc(100% - 28px)" rx="12" fill="#1e293b" stroke="#38bdf8" stroke-width="2"/>',
-        `<text x="28" y="48" fill="#e2e8f0" font-family="Arial, sans-serif" font-size="20" font-weight="700">${title}</text>`,
-        `<text x="28" y="82" fill="#93c5fd" font-family="Arial, sans-serif" font-size="14">LiveDesk Client Thumbnail</text>`,
-        `<text x="28" y="${height - 30}" fill="#94a3b8" font-family="Consolas, monospace" font-size="12">${now}</text>`,
-        '</svg>'
-    ].join('');
-
-    return {
-        frameSeq,
-        width,
-        height,
-        sourceWidth: width,
-        sourceHeight: height,
-        mimeType: 'image/svg+xml',
-        data: Buffer.from(svg, 'utf8').toString('base64'),
-        capturedAt: now
-    };
 }
 
-function readJpegDimensions(buffer) {
-    if (!Buffer.isBuffer(buffer) || buffer.length < 4 || buffer[0] !== 0xff || buffer[1] !== 0xd8) {
-        return { width: 0, height: 0 };
-    }
-
-    let offset = 2;
-    while (offset + 9 < buffer.length) {
-        if (buffer[offset] !== 0xff) {
-            offset += 1;
-            continue;
-        }
-
-        const marker = buffer[offset + 1];
-        const blockLength = buffer.readUInt16BE(offset + 2);
-        if (blockLength < 2) {
-            break;
-        }
-
-        const isStartOfFrame = marker >= 0xc0
-            && marker <= 0xcf
-            && ![0xc4, 0xc8, 0xcc].includes(marker);
-        if (isStartOfFrame) {
-            return {
-                height: buffer.readUInt16BE(offset + 5),
-                width: buffer.readUInt16BE(offset + 7)
-            };
-        }
-
-        offset += 2 + blockLength;
-    }
-
-    return { width: 0, height: 0 };
-}
-
-function normalizeMonitorIndex(value, fallback = 0) {
-    return clampInteger(value, 0, 63, fallback);
-}
-
-async function captureNativeDesktopFrame(frameSeq, monitorIndex = 0) {
-    const screenshotModule = await import('node-screenshots');
-    const Monitor = screenshotModule.Monitor || screenshotModule.default?.Monitor;
-    if (!Monitor?.all) {
-        throw new Error('node-screenshots Monitor API is unavailable.');
-    }
-
-    const monitors = Monitor.all();
-    const selectedIndex = Math.max(0, Math.min(monitors.length - 1, normalizeMonitorIndex(monitorIndex)));
-    const monitor = monitors[selectedIndex] || monitors.find(item => item?.isPrimary?.() === true) || monitors[0];
-    if (!monitor?.captureImage) {
-        throw new Error('No capturable desktop monitor was found.');
-    }
-
-    const image = await monitor.captureImage();
-    const jpeg = await image.toJpeg();
-    const buffer = Buffer.isBuffer(jpeg) ? jpeg : Buffer.from(jpeg);
-    if (buffer.toString('base64').length > MAX_FRAME_BASE64_CHARS) {
-        throw new Error('Desktop capture exceeded the remote frame size limit.');
-    }
-
-    const dimensions = readJpegDimensions(buffer);
-    return {
-        frameSeq,
-        width: dimensions.width,
-        height: dimensions.height,
-        sourceWidth: dimensions.width,
-        sourceHeight: dimensions.height,
-        mimeType: 'image/jpeg',
-        data: buffer.toString('base64'),
-        monitorIndex: selectedIndex,
-        monitorCount: Math.max(1, monitors.length),
-        capturedAt: new Date().toISOString()
-    };
-}
-
-async function captureDesktopThumbnailFrame(payload, frameSeq) {
-    return await captureNativeDesktopFrame(frameSeq, payload?.monitorIndex ?? payload?.screenIndex ?? payload?.displayIndex);
-}
-
-async function captureScreenFrame(options, payload, frameSeq, capability = 'thumbnail') {
-    const enabled = capability === 'live' ? options.liveEnabled : options.thumbnailEnabled;
-    if (!enabled) {
-        throw new Error(`${capability} capability is disabled`);
-    }
-
-    return options.fakeThumbnail
-        ? createFakeThumbnailFrame(options, payload, frameSeq)
-        : await captureDesktopThumbnailFrame(payload, frameSeq);
-}
-
-async function captureThumbnailFrame(options, payload, frameSeq) {
-    return await captureScreenFrame(options, payload, frameSeq, 'thumbnail');
-}
-
-function normalizeApprovalLevel(value) {
-    const level = String(value || 'task-only').trim().toLowerCase();
-    return level === 'ai-assist' ? 'ai-assist' : 'task-only';
+async function resolveAgentPath(options, value, permissionMode, rejectSensitive = true) {
+    const base = normalizeDirectoryPath(options.filesDir || undefined);
+    const text = String(value || '').replace(/\0/g, '').trim();
+    if (!text || text.length > 600) throw new Error('path is invalid');
+    const resolved = path.resolve(path.isAbsolute(text) ? text : path.join(base, text));
+    const relative = path.relative(base, resolved);
+    if (permissionMode !== 'full-access' && (relative === '..' || relative.startsWith(`..${path.sep}`) || path.isAbsolute(relative))) throw new Error('path is outside the LiveDesk files directory for this permission mode');
+    if (permissionMode !== 'full-access') await assertAgentPathDoesNotTraverseLink(base, resolved);
+    if (rejectSensitive && isSensitiveAgentPath(resolved)) throw new Error('credential and secret paths are not available');
+    return resolved;
 }
-
-function buildAiPrompt(options, payload, instruction) {
-    const title = String(payload?.title || 'Remote AI task').trim();
-    return [
-        'You are the LiveDesk client AI assistant running on a controlled remote computer.',
-        'Complete the LiveDesk Hub task as a text-only assistant.',
-        'Do not claim you used shell commands, file writes, browser automation, keyboard input, or mouse input.',
-        'If the task requires external side effects, explain what would be needed and stop.',
-        '',
-        `Device: ${options.name} (${os.hostname()}, ${os.platform()} ${os.release()}, ${os.arch()})`,
-        `Task title: ${title}`,
-        '',
-        'Hub instruction:',
-        instruction
-    ].join('\n');
+
+function runNodeAgentProcess(executable, args, timeoutMs = 15000, cwd = undefined) {
+    return new Promise((resolve, reject) => {
+        const child = spawn(executable, args, { cwd, windowsHide: true, shell: false, stdio: ['ignore', 'pipe', 'pipe'] });
+        let output = '';
+        let timedOut = false;
+        const append = chunk => { output = `${output}${String(chunk || '')}`.replace(/[\0\r]/g, ' ').slice(0, MAX_AGENT_OUTPUT_CHARS); };
+        child.stdout.on('data', append);
+        child.stderr.on('data', append);
+        const timer = setTimeout(() => {
+            timedOut = true;
+            child.kill('SIGTERM');
+            setTimeout(() => child.kill('SIGKILL'), 1000).unref?.();
+        }, Math.max(1000, Math.min(30000, Number(timeoutMs) || 15000)));
+        child.once('error', error => { clearTimeout(timer); reject(error); });
+        child.once('close', code => { clearTimeout(timer); resolve({ output: redactAgentOutput(`${output}${timedOut ? '\n[timeout]' : ''}`.trim()), exitCode: timedOut ? -1 : code ?? -1, timedOut }); });
+    });
+}
+
+function redactAgentOutput(value) {
+    let output = String(value || '').replace(/[\0\r]/g, ' ');
+    output = output.replace(/\b(token|secret|password|api[-_]?key|authorization|private[-_]?key|connection[-_]?string|access[-_]?key|client[-_]?secret)\b\s*[:=]\s*("[^"]*"|'[^']*'|[^\s,;]+)/gi, '$1=[redacted]');
+    output = output.replace(/\bBearer\s+[A-Za-z0-9._~+/=-]+/gi, 'Bearer [redacted]');
+    output = output.replace(/^(\s*(?:set\s+)?(?:[A-Z_][A-Z0-9_]*(?:TOKEN|SECRET|PASSWORD|KEY|AUTH|CREDENTIAL|CONNECTION)[A-Z0-9_]*)\s*=\s*).+$/gim, '$1[redacted]');
+    return output.slice(0, MAX_AGENT_OUTPUT_CHARS);
+}
+
+function normalizeNodeProcessKey(value) {
+    return path.basename(String(value || '').trim()).toLowerCase().replace(/\.(exe|bin)$/i, '');
 }
 
-function extractResponseText(response) {
-    if (typeof response?.output_text === 'string' && response.output_text.trim()) {
-        return response.output_text.trim();
-    }
-
-    const parts = [];
-    if (Array.isArray(response?.output)) {
-        for (const item of response.output) {
-            if (!Array.isArray(item?.content)) {
+function parseWindowsCommandLine(commandLine) {
+    const text = String(commandLine || '').trim();
+    const parsed = [];
+    let index = 0;
+    while (index < text.length) {
+        while (/\s/.test(text[index] || '')) index += 1;
+        if (index >= text.length) break;
+        let value = '';
+        let quoted = false;
+        while (index < text.length) {
+            const character = text[index];
+            if (character === '\\') {
+                let slashCount = 0;
+                while (text[index + slashCount] === '\\') slashCount += 1;
+                const next = text[index + slashCount];
+                if (next === '"') {
+                    value += '\\'.repeat(Math.floor(slashCount / 2));
+                    index += slashCount;
+                    if (slashCount % 2 === 1) {
+                        value += '"';
+                        index += 1;
+                    } else {
+                        quoted = !quoted;
+                        index += 1;
+                    }
+                } else {
+                    value += '\\'.repeat(slashCount);
+                    index += slashCount;
+                }
                 continue;
             }
-
-            for (const content of item.content) {
-                if (typeof content?.text === 'string') {
-                    parts.push(content.text);
-                }
-                if (typeof content?.output_text === 'string') {
-                    parts.push(content.output_text);
-                }
+            if (character === '"') {
+                quoted = !quoted;
+                index += 1;
+                continue;
             }
+            if (/\s/.test(character) && !quoted) break;
+            value += character;
+            index += 1;
         }
+        parsed.push(value);
+        while (/\s/.test(text[index] || '')) index += 1;
     }
-
-    return parts.join('\n').trim();
-}
-
-async function runAiAssistTask(options, payload, instruction) {
-    if (!options.aiEnabled) {
-        throw new Error('AI assist capability is disabled. Start the agent with --ai to enable it.');
-    }
-
-    if (options.fakeAi) {
-        return {
-            text: [
-                `Fake AI assist completed on ${options.name}.`,
-                '',
-                `Instruction: ${instruction.slice(0, 500)}`,
-                '',
-                'No shell, file, input, browser, or persistent side effects were performed.'
-            ].join('\n'),
-            model: 'fake-ai',
-            responseId: `fake-ai-${String(payload?.taskId || crypto.randomUUID()).slice(0, 96)}`
-        };
-    }
-
-    if (!options.openAiApiKey) {
-        throw new Error('OPENAI_API_KEY is required for --ai remote tasks.');
-    }
-
-    const openaiModule = await import('openai');
-    const OpenAI = openaiModule.default || openaiModule.OpenAI;
-    const client = new OpenAI({ apiKey: options.openAiApiKey });
-    const model = String(payload?.model || options.aiModel || DEFAULT_AI_MODEL).trim() || DEFAULT_AI_MODEL;
-    const response = await client.responses.create({
-        model,
-        input: buildAiPrompt(options, payload, instruction)
-    });
-    const text = extractResponseText(response);
-    if (!text) {
-        throw new Error('AI assist returned no text output.');
-    }
-
-    return {
-        text: text.slice(0, MAX_AI_OUTPUT_CHARS),
-        model,
-        responseId: response?.id || ''
-    };
-}
-
-function clampInteger(value, min, max, fallback) {
-    const number = Number(value);
-    if (!Number.isFinite(number)) {
-        return fallback;
-    }
-
-    return Math.max(min, Math.min(max, Math.floor(number)));
+    return parsed;
 }
 
-function stopLiveStream(activeStreams, streamId = '') {
-    if (streamId) {
-        const existing = activeStreams.get(streamId);
-        if (existing?.timer) {
-            clearInterval(existing.timer);
-        }
-        activeStreams.delete(streamId);
-        return existing ? 1 : 0;
-    }
-
-    let stopped = 0;
-    for (const stream of activeStreams.values()) {
-        if (stream?.timer) {
-            clearInterval(stream.timer);
-            stopped += 1;
-        }
+function decodeUtf16Base64(value) {
+    try {
+        return Buffer.from(String(value || ''), 'base64').toString('utf16le');
+    } catch {
+        return '';
     }
-    activeStreams.clear();
-    return stopped;
 }
 
-function startLiveStream(socket, options, message, nextFrameSeq, activeStreams) {
-    if (!options.liveEnabled) {
-        throw new Error('live stream capability is disabled');
+function decodeNullSeparatedBase64(value) {
+    try {
+        return Buffer.from(String(value || ''), 'base64').toString('utf8');
+    } catch {
+        return '';
     }
-
-    const payload = message.payload || {};
-    const streamId = String(payload.streamId || `live-${Date.now()}`)
-        .replace(/[^a-zA-Z0-9_.:-]/g, '-')
-        .slice(0, 128) || `live-${Date.now()}`;
-    const fps = clampInteger(payload.fps, 1, MAX_LIVE_FPS, DEFAULT_LIVE_FPS);
-    const intervalMs = Math.max(33, Math.round(1000 / fps));
-    stopLiveStream(activeStreams, streamId);
-
-    const stream = {
-        streamId,
-        fps,
-        intervalMs,
-        inFlight: false,
-        stopped: false,
-        frameDrops: 0,
-        timer: null
-    };
-    console.log('전송모드 - mode1-jpeg (Mode 1 - Test JPEG Binary)');
-
-    const captureAndSend = async () => {
-        if (stream.stopped || stream.inFlight || socket.destroyed) {
-            if (stream.inFlight) {
-                stream.frameDrops += 1;
-            }
-            return;
-        }
-
-        stream.inFlight = true;
-        try {
-            const frame = await captureScreenFrame(options, payload, nextFrameSeq(), 'live');
-            if (String(frame.data || '').length > MAX_FRAME_BASE64_CHARS) {
-                stream.frameDrops += 1;
-                return;
-            }
-
-            const sent = writeJsonLine(socket, {
-                type: 'stream.frame',
-                commandId: message.commandId,
-                streamId,
-                frameSeq: frame.frameSeq,
-                width: frame.width,
-                height: frame.height,
-                sourceWidth: frame.sourceWidth || frame.width,
-                sourceHeight: frame.sourceHeight || frame.height,
-                mimeType: frame.mimeType,
-                capturedAt: frame.capturedAt,
-                fps,
-                mode: 'mode1-jpeg',
-                monitorIndex: frame.monitorIndex ?? 0,
-                monitorCount: frame.monitorCount ?? 1,
-                droppedByAgent: stream.frameDrops,
-                data: frame.data
-            });
-
-            if (!sent) {
-                stream.stopped = true;
-                stopLiveStream(activeStreams, streamId);
-            }
-        } catch {
-            stream.frameDrops += 1;
-        } finally {
-            stream.inFlight = false;
-        }
-    };
-
-    stream.timer = setInterval(() => {
-        captureAndSend().catch(() => {
-            stream.frameDrops += 1;
-        });
-    }, intervalMs);
-    stream.timer.unref?.();
-    activeStreams.set(streamId, stream);
-    captureAndSend().catch(() => {
-        stream.frameDrops += 1;
-    });
-    return { streamId, fps, intervalMs };
-}
-
-function isSensitiveAgentPath(value) {
-    const normalized = String(value || '').replaceAll('\\', '/').toLowerCase();
-    return normalized.includes('/.codex/') || normalized.endsWith('/auth.json') || normalized.includes('/.ssh/') || normalized.includes('/id_rsa') || normalized.endsWith('.pem') || normalized.endsWith('.key') || normalized.endsWith('/.env') || normalized.includes('/credential') || normalized.includes('/secret') || normalized.includes('/password');
-}
-
-function resolveAgentPath(options, value, permissionMode, rejectSensitive = true) {
-    const base = normalizeDirectoryPath(options.filesDir || undefined);
-    const text = String(value || '').replace(/\0/g, '').trim();
-    if (!text || text.length > 600) throw new Error('path is invalid');
-    const resolved = path.resolve(path.isAbsolute(text) ? text : path.join(base, text));
-    const relative = path.relative(base, resolved);
-    if (permissionMode !== 'full-access' && (relative === '..' || relative.startsWith(`..${path.sep}`) || path.isAbsolute(relative))) throw new Error('path is outside the LiveDesk files directory for this permission mode');
-    if (rejectSensitive && isSensitiveAgentPath(resolved)) throw new Error('credential and secret paths are not available');
-    return resolved;
 }
 
-function runNodeAgentProcess(executable, args, timeoutMs = 15000, cwd = undefined) {
-    return new Promise((resolve, reject) => {
-        const child = spawn(executable, args, { cwd, windowsHide: true, shell: false, stdio: ['ignore', 'pipe', 'pipe'] });
-        let output = '';
-        let timedOut = false;
-        const append = chunk => { output = `${output}${String(chunk || '')}`.replace(/[\0\r]/g, ' ').slice(0, MAX_AGENT_OUTPUT_CHARS); };
-        child.stdout.on('data', append);
-        child.stderr.on('data', append);
-        const timer = setTimeout(() => {
-            timedOut = true;
-            child.kill('SIGTERM');
-            setTimeout(() => child.kill('SIGKILL'), 1000).unref?.();
-        }, Math.max(1000, Math.min(30000, Number(timeoutMs) || 15000)));
-        child.once('error', error => { clearTimeout(timer); reject(error); });
-        child.once('close', code => { clearTimeout(timer); resolve({ output: redactAgentOutput(`${output}${timedOut ? '\n[timeout]' : ''}`.trim()), exitCode: timedOut ? -1 : code ?? -1, timedOut }); });
-    });
-}
-
-function redactAgentOutput(value) {
-    let output = String(value || '').replace(/[\0\r]/g, ' ');
-    output = output.replace(/\b(token|secret|password|api[-_]?key|authorization|private[-_]?key|connection[-_]?string|access[-_]?key|client[-_]?secret)\b\s*[:=]\s*("[^"]*"|'[^']*'|[^\s,;]+)/gi, '$1=[redacted]');
-    output = output.replace(/\bBearer\s+[A-Za-z0-9._~+/=-]+/gi, 'Bearer [redacted]');
-    output = output.replace(/^(\s*(?:set\s+)?(?:[A-Z_][A-Z0-9_]*(?:TOKEN|SECRET|PASSWORD|KEY|AUTH|CREDENTIAL|CONNECTION)[A-Z0-9_]*)\s*=\s*).+$/gim, '$1[redacted]');
-    return output.slice(0, MAX_AGENT_OUTPUT_CHARS);
-}
-
-async function findNodeProcessExecutable(processName) {
+async function findNodeProcessDetails(processName) {
     const name = String(processName || '').trim();
-    if (!name) return '';
+    if (!name) return null;
     if (process.platform === 'win32') {
         const result = await runNodeAgentProcess('powershell.exe', [
             '-NoProfile', '-NonInteractive', '-Command',
-            '$name=$args[0]; $p=Get-CimInstance Win32_Process | Where-Object { $_.Name -ieq $name } | Select-Object -First 1 -ExpandProperty ExecutablePath; if($p){[Console]::Out.Write($p)}',
+            '$name=$args[0]; $p=Get-CimInstance Win32_Process | Where-Object { $_.Name -ieq $name } | Select-Object -First 1; if($p){ $bytes=[Text.Encoding]::Unicode.GetBytes([string]$p.CommandLine); [Console]::Out.WriteLine([string]$p.ProcessId); [Console]::Out.WriteLine([string]$p.ExecutablePath); [Console]::Out.Write([Convert]::ToBase64String($bytes)) }',
             name
         ], 10000);
-        return result.exitCode === 0 ? String(result.output || '').trim().split(/\r?\n/)[0] : '';
+        if (result.exitCode !== 0) return null;
+        const lines = String(result.output || '').trim().split(/\r?\n/);
+        const executable = String(lines[1] || '').trim();
+        if (!lines[0] || !executable) return null;
+        const commandLine = decodeUtf16Base64(lines[2]);
+        const parsed = parseWindowsCommandLine(commandLine);
+        return { pid: Number(lines[0]) || 0, executable, args: parsed.length > 1 ? parsed.slice(1) : null, workingDirectory: null, metadataSource: 'process-command-line' };
     }
     if (process.platform === 'linux') {
-        const result = await runNodeAgentProcess('/bin/sh', ['-lc', 'pid=$(pgrep -xo -- "$1" || true); if [ -n "$pid" ] && [ -e "/proc/$pid/exe" ]; then readlink -f "/proc/$pid/exe"; fi', 'livedesk-process-path', name], 10000);
-        return result.exitCode === 0 ? String(result.output || '').trim().split(/\r?\n/)[0] : '';
-    }
-    return '';
-}
-
-async function persistNodeEnvironmentVariable(name, value) {
-    const variableName = String(name || '').trim();
-    const variableValue = String(value ?? '');
-    if (process.platform === 'win32') {
-        const result = await runNodeAgentProcess('setx.exe', [variableName, variableValue], 15000);
-        if (result.exitCode !== 0 || result.timedOut) throw new Error(`Persistent environment update failed (exit ${result.exitCode}).`);
-        process.env[variableName] = variableValue;
-        return { persisted: true, scope: 'user', output: result.output };
-    }
-    const profilePath = path.join(os.homedir(), '.profile');
-    const marker = `# LiveDesk managed environment: ${variableName}`;
-    const quoted = `'${variableValue.replaceAll("'", "'\\\"'\\\"'")}'`;
-    let profile = '';
-    try { profile = await fs.readFile(profilePath, 'utf8'); } catch { /* create on demand */ }
-    const lines = profile.split(/\r?\n/).filter(line => !line.includes(marker));
-    while (lines.length && lines[lines.length - 1] === '') lines.pop();
-    lines.push(marker, `export ${variableName}=${quoted}`);
-    await fs.writeFile(profilePath, `${lines.join('\n')}\n`, { encoding: 'utf8', mode: 0o600 });
-    process.env[variableName] = variableValue;
-    return { persisted: true, scope: 'user-profile', path: profilePath };
+        const result = await runNodeAgentProcess('/bin/sh', ['-lc', 'pid=$(pgrep -xo -- "$1" || true); if [ -n "$pid" ] && [ -e "/proc/$pid/exe" ]; then printf "%s\\n%s\\n%s\\n" "$pid" "$(readlink -f "/proc/$pid/exe")" "$(readlink -f "/proc/$pid/cwd")"; base64 -w0 "/proc/$pid/cmdline"; fi', 'livedesk-process-details', name], 10000);
+        if (result.exitCode !== 0) return null;
+        const lines = String(result.output || '').trim().split(/\r?\n/);
+        const executable = String(lines[1] || '').trim();
+        const workingDirectory = String(lines[2] || '').trim();
+        if (!lines[0] || !executable) return null;
+        const parsed = decodeNullSeparatedBase64(lines[3]).split('\0').filter(Boolean);
+        return { pid: Number(lines[0]) || 0, executable, args: parsed.length > 1 ? parsed.slice(1) : null, workingDirectory: workingDirectory || null, metadataSource: 'proc' };
+    }
+    if (process.platform === 'darwin') {
+        const result = await runNodeAgentProcess('/bin/sh', ['-lc', 'pid=$(pgrep -xo -- "$1" || true); if [ -n "$pid" ]; then exe=$(ps -p "$pid" -o comm= | sed "s/^ *//"); cwd=$(lsof -a -p "$pid" -d cwd -Fn 2>/dev/null | sed -n "s/^n//p" | head -n 1); command=$(ps -p "$pid" -o command=); printf "%s\\n%s\\n%s\\n" "$pid" "$exe" "$cwd"; printf "%s" "$command" | base64 | tr -d "\\n"; fi', 'livedesk-process-details', name], 10000);
+        if (result.exitCode !== 0) return null;
+        const lines = String(result.output || '').trim().split(/\r?\n/);
+        const executable = String(lines[1] || '').trim();
+        const workingDirectory = String(lines[2] || '').trim();
+        if (!lines[0] || !executable) return null;
+        const parsed = parseWindowsCommandLine(Buffer.from(String(lines[3] || ''), 'base64').toString('utf8'));
+        return { pid: Number(lines[0]) || 0, executable, args: parsed.length > 1 ? parsed.slice(1) : null, workingDirectory: workingDirectory || null, metadataSource: 'ps-lsof' };
+    }
+    return null;
 }
-
+
+async function persistNodeEnvironmentVariable(name, value) {
+    const variableName = String(name || '').trim();
+    const variableValue = String(value ?? '');
+    if (process.platform === 'win32') {
+        const result = await runNodeAgentProcess('setx.exe', [variableName, variableValue], 15000);
+        if (result.exitCode !== 0 || result.timedOut) throw new Error(`Persistent environment update failed (exit ${result.exitCode}).`);
+        process.env[variableName] = variableValue;
+        return { persisted: true, scope: 'user', output: result.output };
+    }
+    const profilePath = path.join(os.homedir(), '.profile');
+    const marker = `# LiveDesk managed environment: ${variableName}`;
+    const quoted = `'${variableValue.replaceAll("'", "'\\\"'\\\"'")}'`;
+    let profile = '';
+    try { profile = await fs.readFile(profilePath, 'utf8'); } catch { /* create on demand */ }
+    const lines = profile.split(/\r?\n/).filter(line => !line.includes(marker));
+    while (lines.length && lines[lines.length - 1] === '') lines.pop();
+    lines.push(marker, `export ${variableName}=${quoted}`);
+    await fs.writeFile(profilePath, `${lines.join('\n')}\n`, { encoding: 'utf8', mode: 0o600 });
+    process.env[variableName] = variableValue;
+    return { persisted: true, scope: 'user-profile', path: profilePath };
+}
+
 async function executeNodeAgentOperation(options, operation, payload = {}) {
-    const permissionMode = String(payload.permissionMode || 'ask');
+    const permissionMode = String(payload.permissionMode || 'ask');
     const args = payload.toolArguments && typeof payload.toolArguments === 'object' ? payload.toolArguments : payload;
     if (operation === 'file.read') {
-        const filePath = resolveAgentPath(options, args.path, permissionMode);
-        const info = await fs.stat(filePath);
-        const maxBytes = Math.max(1, Math.min(65536, Number(args.maxBytes) || 65536));
-        const content = (await fs.readFile(filePath)).subarray(0, maxBytes).toString('utf8');
-        return { summary: `Read ${Buffer.byteLength(content)} bytes from ${path.basename(filePath)}.`, data: { path: filePath, sizeBytes: info.size, returnedBytes: Buffer.byteLength(content), truncated: info.size > Buffer.byteLength(content), content } };
+        const filePath = await resolveAgentPath(options, args.path, permissionMode);
+        const info = await fs.stat(filePath);
+        const maxBytes = Math.max(1, Math.min(65536, Number(args.maxBytes) || 65536));
+        const content = (await fs.readFile(filePath)).subarray(0, maxBytes).toString('utf8');
+        return { summary: `Read ${Buffer.byteLength(content)} bytes from ${path.basename(filePath)}.`, data: { path: filePath, sizeBytes: info.size, returnedBytes: Buffer.byteLength(content), truncated: info.size > Buffer.byteLength(content), content } };
     }
     if (operation === 'file.write') {
-        const filePath = resolveAgentPath(options, args.path, permissionMode);
+        let filePath = await resolveAgentPath(options, args.path, permissionMode);
         const content = String(args.content || '');
         if (Buffer.byteLength(content) > 1048576) throw new Error('file content exceeds the 1 MiB limit');
         await fs.mkdir(path.dirname(filePath), { recursive: true });
+        // Re-check after creating missing parents so a newly introduced link
+        // cannot turn the write into an outside-root operation.
+        filePath = await resolveAgentPath(options, args.path, permissionMode);
         if (args.append === true) await fs.appendFile(filePath, content, 'utf8');
-        else await fs.writeFile(filePath, content, 'utf8');
-        return { summary: `Wrote ${Buffer.byteLength(content)} bytes to ${path.basename(filePath)}.`, data: { path: filePath, sizeBytes: (await fs.stat(filePath)).size, append: args.append === true } };
-    }
+        else await fs.writeFile(filePath, content, 'utf8');
+        return { summary: `Wrote ${Buffer.byteLength(content)} bytes to ${path.basename(filePath)}.`, data: { path: filePath, sizeBytes: (await fs.stat(filePath)).size, append: args.append === true } };
+    }
     if (operation === 'file.delete') {
-        const filePath = resolveAgentPath(options, args.path, permissionMode);
-        if (args.recursive === true) await fs.rm(filePath, { recursive: true, force: false });
-        else await fs.unlink(filePath);
-        return { summary: `Deleted ${path.basename(filePath)}.`, data: { path: filePath, recursive: args.recursive === true } };
-    }
+        const filePath = await resolveAgentPath(options, args.path, permissionMode);
+        if (args.recursive === true) await fs.rm(filePath, { recursive: true, force: false });
+        else await fs.unlink(filePath);
+        return { summary: `Deleted ${path.basename(filePath)}.`, data: { path: filePath, recursive: args.recursive === true } };
+    }
     if (operation === 'file.list') {
-        const directory = resolveAgentPath(options, args.path, permissionMode);
-        const entries = await fs.readdir(directory, { withFileTypes: true });
-        const maxEntries = Math.max(1, Math.min(500, Number(args.maxEntries) || 200));
-        const data = [];
-        for (const entry of entries.slice(0, maxEntries)) {
-            const entryPath = path.join(directory, entry.name);
-            if (isSensitiveAgentPath(entryPath)) continue;
-            data.push({ name: entry.name, path: entryPath, type: entry.isDirectory() ? 'directory' : 'file', sizeBytes: entry.isDirectory() ? 0 : (await fs.stat(entryPath)).size });
-        }
-        return { summary: `Listed ${data.length} entries.`, data: { path: directory, entries: data, truncated: entries.length > maxEntries } };
+        const directory = await resolveAgentPath(options, args.path, permissionMode);
+        const entries = await fs.readdir(directory, { withFileTypes: true });
+        const maxEntries = Math.max(1, Math.min(500, Number(args.maxEntries) || 200));
+        const data = [];
+        for (const entry of entries.slice(0, maxEntries)) {
+            const entryPath = path.join(directory, entry.name);
+            if (isSensitiveAgentPath(entryPath)) continue;
+            data.push({ name: entry.name, path: entryPath, type: entry.isDirectory() ? 'directory' : 'file', sizeBytes: entry.isDirectory() ? 0 : (await fs.stat(entryPath)).size });
+        }
+        return { summary: `Listed ${data.length} entries.`, data: { path: directory, entries: data, truncated: entries.length > maxEntries } };
     }
     if (operation === 'application.launch') {
         const executable = String(args.executable || '').trim();
         if (!executable || executable.length > 400 || /[\0\r\n]/.test(executable)) throw new Error('executable is invalid');
-        const child = spawn(executable, Array.isArray(args.args) ? args.args.slice(0, 32).map(String) : [], { cwd: args.workingDirectory ? resolveAgentPath(options, args.workingDirectory, permissionMode, false) : undefined, detached: true, windowsHide: true, stdio: 'ignore' });
+        const launchArgs = Array.isArray(args.args) ? args.args.slice(0, 32).map(String) : [];
+        const workingDirectory = args.workingDirectory ? await resolveAgentPath(options, args.workingDirectory, permissionMode, false) : process.cwd();
+        const child = spawn(executable, launchArgs, { cwd: workingDirectory, detached: true, windowsHide: true, stdio: 'ignore' });
         child.unref();
-        return { summary: `Started ${path.basename(executable)}.`, data: { executable, pid: child.pid } };
+        launchedProcessRegistry.set(normalizeNodeProcessKey(executable), { executable, args: launchArgs, workingDirectory, metadataSource: 'launch_application' });
+        return { summary: `Started ${path.basename(executable)}.`, data: { executable, args: launchArgs, workingDirectory, pid: child.pid } };
     }
     if (operation === 'process.control') {
         const action = String(args.action || 'stop');
         const processName = String(args.processName || '').trim();
+        const processDetails = await findNodeProcessDetails(processName);
+        if (!processDetails) {
+            if (action === 'restart') throw new Error(`process-not-found: ${processName}`);
+            return { summary: `${processName} is already stopped.`, data: { action, processName, status: 'already-stopped', ok: true } };
+        }
         if (action === 'restart') {
-            const executable = await findNodeProcessExecutable(processName);
-            if (!executable) throw new Error(`Restart is not supported because the executable path for ${processName} could not be resolved.`);
+            const restartMetadata = launchedProcessRegistry.get(normalizeNodeProcessKey(processName)) || processDetails;
+            if (!restartMetadata.executable || !Array.isArray(restartMetadata.args) || !restartMetadata.workingDirectory) {
+                throw new Error(`process-restart-metadata-unavailable: ${processName}`);
+            }
             const stop = await runNodeAgentProcess(process.platform === 'win32' ? 'taskkill' : 'pkill', process.platform === 'win32' ? ['/IM', processName, '/T', '/F'] : ['-TERM', processName]);
-            if (stop.exitCode !== 0 && !stop.timedOut) throw new Error(`Process stop failed before restart (exit ${stop.exitCode}).`);
-            const child = spawn(executable, [], { detached: true, windowsHide: true, stdio: 'ignore' });
+            if (stop.exitCode !== 0 || stop.timedOut) throw new Error(`Process stop failed before restart (exit ${stop.exitCode}).`);
+            const child = spawn(restartMetadata.executable, restartMetadata.args, { cwd: restartMetadata.workingDirectory, detached: true, windowsHide: true, stdio: 'ignore' });
             child.unref();
-            return { summary: `Restarted ${processName}.`, data: { action, processName, stop, restarted: true, pid: child.pid, executable } };
+            return { summary: `Restarted ${processName}.`, data: { action, processName, stop, restarted: true, pid: child.pid, executable: restartMetadata.executable, args: restartMetadata.args, workingDirectory: restartMetadata.workingDirectory, metadataSource: restartMetadata.metadataSource } };
         }
-        const result = await runNodeAgentProcess(process.platform === 'win32' ? 'taskkill' : 'pkill', process.platform === 'win32' ? ['/IM', processName, '/T'] : ['-TERM', processName]);
-        return { summary: `${action} requested for ${processName}.`, data: { action, processName, ...result } };
-    }
-    if (operation === 'application.close') return executeNodeAgentOperation(options, 'process.control', { ...payload, toolArguments: { ...args, action: 'stop' } });
-    if (operation === 'service.control') {
-        const service = String(args.serviceName || '');
-        const action = String(args.action || 'status');
-        const executable = process.platform === 'win32' ? 'sc.exe' : 'systemctl';
+        const result = await runNodeAgentProcess(process.platform === 'win32' ? 'taskkill' : 'pkill', process.platform === 'win32' ? ['/IM', processName, '/T'] : ['-TERM', processName]);
+        return { summary: `${action} requested for ${processName}.`, data: { action, processName, ...result } };
+    }
+    if (operation === 'application.close') return executeNodeAgentOperation(options, 'process.control', { ...payload, toolArguments: { ...args, action: 'stop' } });
+    if (operation === 'service.control') {
+        const service = String(args.serviceName || '');
+        const action = String(args.action || 'status');
+        const executable = process.platform === 'win32' ? 'sc.exe' : 'systemctl';
         const actions = action === 'restart' ? ['stop', 'start'] : [action];
         const results = [];
         for (const step of actions) {
             const result = await runNodeAgentProcess(executable, [step, service]);
             results.push({ action: step, ...result });
             if (result.exitCode !== 0 || result.timedOut) break;
+            if (step === 'stop') {
+                await waitForNodeServiceState(executable, service, 'stopped');
+            } else if (step === 'start') {
+                await waitForNodeServiceState(executable, service, 'running');
+            }
         }
-        const ok = results.length === actions.length && results.every(result => result.exitCode === 0 && !result.timedOut);
-        if (!ok) throw new Error(`Service ${action} failed for ${service}.`);
-        return { summary: `Service ${action} completed for ${service}.`, data: { service, action, results } };
-    }
-    if (operation === 'command.run') {
-        const command = String(args.command || '');
-        const executable = process.platform === 'win32' ? 'cmd.exe' : '/bin/sh';
-        const commandArgs = process.platform === 'win32' ? ['/d', '/s', '/c', command] : ['-lc', command];
-        const result = await runNodeAgentProcess(executable, commandArgs, args.timeoutMs, args.workingDirectory ? resolveAgentPath(options, args.workingDirectory, permissionMode, false) : undefined);
-        return { summary: result.timedOut ? 'Command timed out.' : `Command exited with code ${result.exitCode}.`, data: { ...result, output: redactAgentOutput(result.output) } };
-    }
-    if (operation === 'script.run') {
-        const scriptPath = resolveAgentPath(options, args.path, permissionMode);
-        const executable = process.platform === 'win32' ? 'powershell.exe' : '/bin/sh';
-        const scriptArgs = process.platform === 'win32' ? ['-NoProfile', '-NonInteractive', '-ExecutionPolicy', 'Bypass', '-File', scriptPath, ...(Array.isArray(args.args) ? args.args.slice(0, 32).map(String) : [])] : [scriptPath, ...(Array.isArray(args.args) ? args.args.slice(0, 32).map(String) : [])];
-        const result = await runNodeAgentProcess(executable, scriptArgs, args.timeoutMs);
-        return { summary: result.timedOut ? 'Script timed out.' : `Script exited with code ${result.exitCode}.`, data: { ...result, output: redactAgentOutput(result.output) } };
-    }
-    if (operation === 'software.install') {
-        const manager = String(args.manager || '').toLowerCase();
-        const packageName = String(args.packageName || '');
-        if (!/^[A-Za-z0-9._@:+/-]{1,200}$/.test(packageName)) throw new Error('packageName contains unsupported characters');
-        const commands = { winget: ['winget.exe', ['install', '--id', packageName, '--silent', '--accept-source-agreements', '--accept-package-agreements']], brew: ['brew', ['install', packageName]], apt: ['apt-get', ['install', '-y', packageName]], npm: ['npm', ['install', '--global', args.version ? `${packageName}@${args.version}` : packageName]] };
-        if (!commands[manager]) throw new Error('unsupported package manager');
-        const [executable, commandArgs] = commands[manager];
-        const result = await runNodeAgentProcess(executable, commandArgs, 30000);
-        return { summary: `Package install exited with code ${result.exitCode}.`, data: { manager, packageName, ...result } };
-    }
-    if (operation === 'network.status') return { summary: 'Network status collected.', data: Object.fromEntries(Object.entries(os.networkInterfaces()).map(([name, values]) => [name, (values || []).map(value => ({ address: value.address, family: value.family, internal: value.internal }))])) };
-    if (operation === 'system.power') {
-        const action = String(args.action || '');
-        const delaySec = String(Math.max(0, Math.min(3600, Number(args.delaySec) || 0)));
-        let executable;
-        let powerArgs;
-        if (process.platform === 'win32') {
-            ({ executable, args: powerArgs } = {
-                lock: { executable: 'rundll32.exe', args: ['user32.dll,LockWorkStation'] },
-                sleep: { executable: 'rundll32.exe', args: ['powrprof.dll,SetSuspendState', '0,1,0'] },
-                logoff: { executable: 'shutdown.exe', args: ['/l'] },
-                restart: { executable: 'shutdown.exe', args: ['/r', '/t', delaySec] },
-                shutdown: { executable: 'shutdown.exe', args: ['/s', '/t', delaySec] }
-            }[action] || {});
-        } else {
-            ({ executable, args: powerArgs } = {
-                lock: { executable: 'loginctl', args: ['lock-session'] },
-                sleep: { executable: 'systemctl', args: ['suspend'] },
-                logoff: { executable: 'loginctl', args: ['terminate-user', os.userInfo().username] },
-                restart: { executable: 'systemctl', args: ['reboot'] },
-                shutdown: { executable: 'systemctl', args: ['poweroff'] }
-            }[action] || {});
-        }
-        if (!executable) throw new Error(`Unsupported power action: ${action}.`);
-        const result = await runNodeAgentProcess(executable, powerArgs, 15000);
-        return { summary: `Power action ${action} requested.`, data: result };
-    }
-    if (operation === 'system.configure') {
-        if (args.action === 'set-environment-variable') {
-            if (!/^[A-Za-z_][A-Za-z0-9_]{0,119}$/.test(String(args.name || '')) || /^(PATH|PATHEXT|SYSTEMROOT|WINDIR|COMSPEC)$/i.test(String(args.name))) throw new Error('environment variable name is not allowed');
-            const persistence = await persistNodeEnvironmentVariable(String(args.name), String(args.value ?? ''));
-            return { summary: `Environment variable ${args.name} was persisted.`, data: { action: args.action, name: args.name, changed: true, ...persistence } };
-        }
-        const result = await runNodeAgentProcess(process.platform === 'win32' ? 'tzutil.exe' : 'timedatectl', process.platform === 'win32' ? ['/s', String(args.value || '')] : ['set-timezone', String(args.value || '')]);
-        return { summary: `Timezone update exited with code ${result.exitCode}.`, data: result };
-    }
-    if (operation === 'logs.collect') {
-        const maxLines = Math.max(1, Math.min(500, Number(args.maxLines) || 100));
-        const result = await runNodeAgentProcess(process.platform === 'win32' ? 'powershell.exe' : 'journalctl', process.platform === 'win32' ? ['-NoProfile', '-NonInteractive', '-Command', `Get-WinEvent -LogName System -MaxEvents ${maxLines} | Format-List`] : ['-n', String(maxLines), '--no-pager', '-o', 'short']);
-        return { summary: 'Recent logs collected.', data: { source: args.source || 'system', ...result, output: result.output.replace(/(token|password|secret|api[-_]?key|authorization)\s*[:=]\s*[^\s]+/gi, '$1=[redacted]') } };
-    }
-    throw new Error(`Unsupported command: ${operation}`);
+        const ok = results.length === actions.length && results.every(result => result.exitCode === 0 && !result.timedOut);
+        if (!ok) throw new Error(`Service ${action} failed for ${service}.`);
+        return { summary: `Service ${action} completed for ${service}.`, data: { service, action, results } };
+    }
+    if (operation === 'command.run') {
+        const command = String(args.command || '');
+        const executable = process.platform === 'win32' ? 'cmd.exe' : '/bin/sh';
+        const commandArgs = process.platform === 'win32' ? ['/d', '/s', '/c', command] : ['-lc', command];
+        const result = await runNodeAgentProcess(executable, commandArgs, args.timeoutMs, args.workingDirectory ? await resolveAgentPath(options, args.workingDirectory, permissionMode, false) : undefined);
+        return { summary: result.timedOut ? 'Command timed out.' : `Command exited with code ${result.exitCode}.`, data: { ...result, output: redactAgentOutput(result.output) } };
+    }
+    if (operation === 'script.run') {
+        const scriptPath = await resolveAgentPath(options, args.path, permissionMode);
+        const executable = process.platform === 'win32' ? 'powershell.exe' : '/bin/sh';
+        const scriptArgs = process.platform === 'win32' ? ['-NoProfile', '-NonInteractive', '-ExecutionPolicy', 'Bypass', '-File', scriptPath, ...(Array.isArray(args.args) ? args.args.slice(0, 32).map(String) : [])] : [scriptPath, ...(Array.isArray(args.args) ? args.args.slice(0, 32).map(String) : [])];
+        const result = await runNodeAgentProcess(executable, scriptArgs, args.timeoutMs);
+        return { summary: result.timedOut ? 'Script timed out.' : `Script exited with code ${result.exitCode}.`, data: { ...result, output: redactAgentOutput(result.output) } };
+    }
+    if (operation === 'software.install') {
+        const manager = String(args.manager || '').toLowerCase();
+        const packageName = String(args.packageName || '');
+        if (!/^[A-Za-z0-9._@:+/-]{1,200}$/.test(packageName)) throw new Error('packageName contains unsupported characters');
+        const commands = { winget: ['winget.exe', ['install', '--id', packageName, '--silent', '--accept-source-agreements', '--accept-package-agreements']], brew: ['brew', ['install', packageName]], apt: ['apt-get', ['install', '-y', packageName]], npm: ['npm', ['install', '--global', args.version ? `${packageName}@${args.version}` : packageName]] };
+        if (!commands[manager]) throw new Error('unsupported package manager');
+        const [executable, commandArgs] = commands[manager];
+        const result = await runNodeAgentProcess(executable, commandArgs, 30000);
+        return { summary: `Package install exited with code ${result.exitCode}.`, data: { manager, packageName, ...result } };
+    }
+    if (operation === 'network.status') return { summary: 'Network status collected.', data: Object.fromEntries(Object.entries(os.networkInterfaces()).map(([name, values]) => [name, (values || []).map(value => ({ address: value.address, family: value.family, internal: value.internal }))])) };
+    if (operation === 'system.power') {
+        const action = String(args.action || '');
+        const delaySec = String(Math.max(0, Math.min(3600, Number(args.delaySec) || 0)));
+        let executable;
+        let powerArgs;
+        if (process.platform === 'win32') {
+            ({ executable, args: powerArgs } = {
+                lock: { executable: 'rundll32.exe', args: ['user32.dll,LockWorkStation'] },
+                sleep: { executable: 'rundll32.exe', args: ['powrprof.dll,SetSuspendState', '0,1,0'] },
+                logoff: { executable: 'shutdown.exe', args: ['/l'] },
+                restart: { executable: 'shutdown.exe', args: ['/r', '/t', delaySec] },
+                shutdown: { executable: 'shutdown.exe', args: ['/s', '/t', delaySec] }
+            }[action] || {});
+        } else {
+            ({ executable, args: powerArgs } = {
+                lock: { executable: 'loginctl', args: ['lock-session'] },
+                sleep: { executable: 'systemctl', args: ['suspend'] },
+                logoff: { executable: 'loginctl', args: ['terminate-user', os.userInfo().username] },
+                restart: { executable: 'systemctl', args: ['reboot'] },
+                shutdown: { executable: 'systemctl', args: ['poweroff'] }
+            }[action] || {});
+        }
+        if (!executable) throw new Error(`Unsupported power action: ${action}.`);
+        const result = await runNodeAgentProcess(executable, powerArgs, 15000);
+        return { summary: `Power action ${action} requested.`, data: result };
+    }
+    if (operation === 'system.configure') {
+        if (args.action === 'set-environment-variable') {
+            if (!/^[A-Za-z_][A-Za-z0-9_]{0,119}$/.test(String(args.name || '')) || /^(PATH|PATHEXT|SYSTEMROOT|WINDIR|COMSPEC)$/i.test(String(args.name))) throw new Error('environment variable name is not allowed');
+            const persistence = await persistNodeEnvironmentVariable(String(args.name), String(args.value ?? ''));
+            return { summary: `Environment variable ${args.name} was persisted.`, data: { action: args.action, name: args.name, changed: true, ...persistence } };
+        }
+        const result = await runNodeAgentProcess(process.platform === 'win32' ? 'tzutil.exe' : 'timedatectl', process.platform === 'win32' ? ['/s', String(args.value || '')] : ['set-timezone', String(args.value || '')]);
+        return { summary: `Timezone update exited with code ${result.exitCode}.`, data: result };
+    }
+    if (operation === 'logs.collect') {
+        const maxLines = Math.max(1, Math.min(500, Number(args.maxLines) || 100));
+        const result = await runNodeAgentProcess(process.platform === 'win32' ? 'powershell.exe' : 'journalctl', process.platform === 'win32' ? ['-NoProfile', '-NonInteractive', '-Command', `Get-WinEvent -LogName System -MaxEvents ${maxLines} | Format-List`] : ['-n', String(maxLines), '--no-pager', '-o', 'short']);
+        return { summary: 'Recent logs collected.', data: { source: args.source || 'system', ...result, output: result.output.replace(/(token|password|secret|api[-_]?key|authorization)\s*[:=]\s*[^\s]+/gi, '$1=[redacted]') } };
+    }
+    throw new Error(`Unsupported command: ${operation}`);
 }
 
-const NODE_AGENT_OPERATIONS = new Set(['process.control', 'service.control', 'application.launch', 'application.close', 'file.read', 'file.write', 'file.delete', 'file.list', 'command.run', 'script.run', 'software.install', 'network.status', 'system.power', 'system.configure', 'logs.collect']);
-
-async function handleRemoteCommand(socket, options, message, nextFrameSeq, activeStreams) {
-    const command = String(message.command || '');
-    if (command === 'ping') {
-        writeJsonLine(socket, {
-            type: 'command.result',
-            commandId: message.commandId,
-            result: {
-                pong: true,
-                at: new Date().toISOString()
-            }
-        });
-        return;
-    }
+function normalizeNodeAgentTaskResult(result) {
+    const data = result?.data;
+    const candidates = [result, data, ...(Array.isArray(data?.results) ? data.results : [])];
+    const failedCandidate = candidates.find(candidate => candidate && typeof candidate === 'object' && (
+        candidate.ok === false
+        || candidate.status === 'failed'
+        || candidate.timedOut === true
+        || (Number.isFinite(Number(candidate.exitCode)) && Number(candidate.exitCode) !== 0)
+    ));
+    const ok = result?.ok !== false && !failedCandidate;
+    const error = ok
+        ? ''
+        : String(result?.error || failedCandidate?.error || result?.summary || 'Agent operation failed.').slice(0, 500);
+    return { ...result, ok, status: ok ? 'completed' : 'failed', error };
+}
 
-    if (NODE_AGENT_OPERATIONS.has(command)) {
-        if (!options.taskEnabled) {
-            writeJsonLine(socket, { type: 'command.result', commandId: message.commandId, error: 'remote task capability is disabled' });
-            return;
+const NODE_AGENT_OPERATIONS = new Set(['process.control', 'service.control', 'application.launch', 'application.close', 'file.read', 'file.write', 'file.delete', 'file.list', 'command.run', 'script.run', 'software.install', 'network.status', 'system.power', 'system.configure', 'logs.collect']);
+
+async function handleRemoteCommand(socket, options, message, nextFrameSeq, activeStreams) {
+    const command = String(message.command || '');
+    if (command === 'ping') {
+        writeJsonLine(socket, {
+            type: 'command.result',
+            commandId: message.commandId,
+            result: {
+                pong: true,
+                at: new Date().toISOString()
+            }
+        });
+        return;
+    }
+
+    if (NODE_AGENT_OPERATIONS.has(command)) {
+        if (!options.taskEnabled) {
+            writeJsonLine(socket, { type: 'command.result', commandId: message.commandId, error: 'remote task capability is disabled' });
+            return;
         }
         try {
-            const result = await executeNodeAgentOperation(options, command, message.payload || {});
+            const result = normalizeNodeAgentTaskResult(await executeNodeAgentOperation(options, command, message.payload || {}));
             writeJsonLine(socket, {
                 type: 'command.result',
                 commandId: message.commandId,
-                result: {
+                result: {
                     kind: command,
                     mode: String(message.payload?.permissionMode || 'ask'),
                     taskId: String(message.payload?.taskId || '').slice(0, 128),
-                    status: 'completed',
+                    ok: result.ok,
+                    status: result.status,
                     summary: result.summary,
+                    error: result.error || undefined,
                     data: result.data,
-                    sideEffects: ['file.read', 'file.list', 'network.status', 'logs.collect'].includes(command) ? 'none' : 'audited',
-                    completedAt: new Date().toISOString()
-                }
-            });
+                    sideEffects: ['file.read', 'file.list', 'network.status', 'logs.collect'].includes(command) ? 'none' : 'audited',
+                    completedAt: new Date().toISOString()
+                }
+            });
         } catch (error) {
-            writeJsonLine(socket, { type: 'command.result', commandId: message.commandId, error: error?.message || String(error) });
-        }
-        return;
-    }
-
-    if (command === 'agent.task') {
-        if (!options.taskEnabled) {
+            const messageText = error?.message || String(error);
             writeJsonLine(socket, {
                 type: 'command.result',
                 commandId: message.commandId,
-                error: 'remote task capability is disabled'
+                error: messageText,
+                result: { ok: false, status: 'failed', error: messageText, completedAt: new Date().toISOString() }
             });
-            return;
-        }
-
-        const payload = message.payload || {};
-        const instruction = String(payload.instruction || '').replace(/\0/g, '').trim().slice(0, 4000);
-        if (!instruction) {
-            writeJsonLine(socket, {
-                type: 'command.result',
-                commandId: message.commandId,
-                error: 'missing task instruction'
-            });
-            return;
-        }
-
-        const approvalLevel = normalizeApprovalLevel(payload.approvalLevel);
-        const completedAt = new Date().toISOString();
-        const title = String(payload.title || instruction.split(/\r?\n/)[0] || 'Remote task')
-            .replace(/[\r\n\t]/g, ' ')
-            .trim()
-            .slice(0, 120);
-        if (approvalLevel === 'ai-assist') {
-            try {
-                const aiResult = await runAiAssistTask(options, payload, instruction);
-                writeJsonLine(socket, {
-                    type: 'command.result',
-                    commandId: message.commandId,
-                    result: {
-                        kind: 'agent.task',
-                        mode: 'ai-assist',
-                        taskId: String(payload.taskId || '').slice(0, 128),
-                        title,
-                        status: 'completed',
-                        summary: aiResult.text,
-                        sideEffects: 'none',
-                        model: aiResult.model,
-                        responseId: aiResult.responseId,
-                        instructionPreview: instruction.slice(0, 320),
-                        completedAt: new Date().toISOString()
-                    }
-                });
-            } catch (error) {
-                writeJsonLine(socket, {
-                    type: 'command.result',
-                    commandId: message.commandId,
-                    error: error?.message || String(error)
-                });
-            }
-            return;
-        }
-
-        writeJsonLine(socket, {
-            type: 'command.result',
-            commandId: message.commandId,
-            result: {
-                kind: 'agent.task',
-                mode: 'task-only',
-                taskId: String(payload.taskId || '').slice(0, 128),
-                title,
-                status: 'completed',
-                summary: `Task received by ${options.name}. Safe task-only mode confirmed receipt without shell, file, input, or browser side effects.`,
-                sideEffects: 'none',
-                instructionPreview: instruction.slice(0, 320),
-                device: {
-                    hostname: os.hostname(),
-                    platform: os.platform(),
-                    release: os.release(),
-                    arch: os.arch()
-                },
-                completedAt
-            }
-        });
-        return;
-    }
-
-    if (command === 'thumbnail.capture') {
-        try {
-            const frameSeq = nextFrameSeq();
-            const frame = await captureThumbnailFrame(options, message.payload || {}, frameSeq);
-            writeJsonLine(socket, {
-                type: 'thumbnail.frame',
-                commandId: message.commandId,
-                streamId: message.payload?.streamId || 'thumbnail',
-                frameSeq: frame.frameSeq,
-                width: frame.width,
-                height: frame.height,
-                sourceWidth: frame.sourceWidth || frame.width,
-                sourceHeight: frame.sourceHeight || frame.height,
-                mimeType: frame.mimeType,
-                capturedAt: frame.capturedAt,
-                data: frame.data
-            });
-            writeJsonLine(socket, {
-                type: 'command.result',
-                commandId: message.commandId,
-                result: {
-                    thumbnail: true,
-                    frameSeq: frame.frameSeq,
-                    width: frame.width,
-                    height: frame.height,
-                    sourceWidth: frame.sourceWidth || frame.width,
-                    sourceHeight: frame.sourceHeight || frame.height,
-                    capturedAt: frame.capturedAt
-                }
-            });
-        } catch (error) {
-            writeJsonLine(socket, {
-                type: 'command.result',
-                commandId: message.commandId,
-                error: error?.message || String(error)
-            });
-        }
-        return;
-    }
-
-    if (command === 'stream.start') {
-        try {
-            const started = startLiveStream(socket, options, message, nextFrameSeq, activeStreams);
-            writeJsonLine(socket, {
-                type: 'command.result',
-                commandId: message.commandId,
-                result: {
-                    stream: true,
-                    started: true,
-                    streamId: started.streamId,
-                    fps: started.fps,
-                    intervalMs: started.intervalMs,
-                    mode: 'mode1-jpeg',
-                    viewOnly: true,
-                    inputControl: false,
-                    startedAt: new Date().toISOString()
-                }
-            });
-        } catch (error) {
-            writeJsonLine(socket, {
-                type: 'command.result',
-                commandId: message.commandId,
-                error: error?.message || String(error)
-            });
-        }
-        return;
-    }
-
-    if (command === 'stream.stop') {
-        const streamId = String(message.payload?.streamId || '').slice(0, 128);
-        const stopped = stopLiveStream(activeStreams, streamId);
-        writeJsonLine(socket, {
-            type: 'command.result',
-            commandId: message.commandId,
-            result: {
-                stream: true,
-                stopped: true,
-                streamId,
-                stoppedCount: stopped,
-                stoppedAt: new Date().toISOString()
-            }
-        });
-        return;
-    }
-
-    if (command === 'file.transfer') {
-        try {
-            const result = await handleFileTransferCommand(options, message.payload || {});
-            writeJsonLine(socket, {
-                type: 'command.result',
-                commandId: message.commandId,
-                result
-            });
-        } catch (error) {
-            writeJsonLine(socket, {
-                type: 'command.result',
-                commandId: message.commandId,
-                error: error?.message || String(error)
-            });
-        }
-        return;
-    }
-
-    if (command === 'file.transfer.chunk') {
-        try {
-            const result = await handleFileTransferChunkCommand(options, message.payload || {});
-            writeJsonLine(socket, {
-                type: 'command.result',
-                commandId: message.commandId,
-                result
-            });
-        } catch (error) {
-            writeJsonLine(socket, {
-                type: 'command.result',
-                commandId: message.commandId,
-                error: error?.message || String(error)
-            });
-        }
-        return;
-    }
-
-    if (command === 'audio.start' || command === 'audio.stop') {
-        writeJsonLine(socket, {
-            type: 'command.result',
-            commandId: message.commandId,
-            error: 'remote audio is only available in a RemoteFast engine with audio support'
-        });
-        return;
-    }
-
-    if (command === 'input.control') {
-        writeJsonLine(socket, {
-            type: 'command.result',
-            commandId: message.commandId,
-            error: 'input control is only available in the C# RemoteFast engine'
-        });
-        return;
-    }
-
-    writeJsonLine(socket, {
-        type: 'command.result',
-        commandId: message.commandId,
-        error: `Unsupported command: ${command}`
-    });
-}
-
-function connectOnce(options, deviceId) {
-    const manager = parseManagerAddress(options.manager);
-    return new Promise((resolve, reject) => {
-        const socket = net.createConnection({
-            host: manager.host,
-            port: manager.port
-        });
-
-        let buffer = '';
-        let heartbeatTimer = null;
-        let resolved = false;
-        let frameSeq = 0;
-        const activeStreams = new Map();
-
-        function cleanup() {
-            if (heartbeatTimer) {
-                clearInterval(heartbeatTimer);
-                heartbeatTimer = null;
-            }
-            stopLiveStream(activeStreams);
-        }
-
-        function finish(error = null) {
-            if (resolved) {
-                return;
-            }
-            resolved = true;
-            cleanup();
-            if (!socket.destroyed) {
-                socket.destroy();
-            }
-            if (error) {
-                reject(error);
-            } else {
-                resolve();
-            }
-        }
-
-        socket.setEncoding('utf8');
-        socket.setNoDelay(true);
-        socket.setKeepAlive(true, options.heartbeatMs);
-
-        socket.once('connect', () => {
-            writeJsonLine(socket, {
-                type: 'hello',
-                pairToken: options.pair,
-                deviceId,
-                deviceName: options.name,
-                slotNumber: options.slotNumber || undefined,
-                hostname: os.hostname(),
-                platform: os.platform(),
-                arch: os.arch(),
-                pid: process.pid,
-                agentVersion: AGENT_VERSION,
-                capabilities: {
-                    status: true,
-                    thumbnail: options.thumbnailEnabled,
-                    liveStream: options.liveEnabled,
-                    monitorSelection: true,
-                    screenCount: 1,
-                    monitorCount: 1,
-                    control: false,
-                    audio: false,
-                    remoteAudio: false,
-                    fileTransfer: true,
-                    remoteFiles: true,
-                    fileTransferMaxBytes: MAX_FILE_TRANSFER_BYTES,
-                    computerAgent: options.taskEnabled,
-                    taskDispatch: options.taskEnabled,
-                    agentApproval: options.taskEnabled,
-                    agentAudit: options.taskEnabled,
-                    agentTools: [...NODE_AGENT_OPERATIONS],
-                    elevation: typeof process.getuid === 'function' ? process.getuid() === 0 : false,
-                    aiAssist: options.taskEnabled && options.aiEnabled && (options.fakeAi || !!options.openAiApiKey),
-                    aiModel: options.aiModel,
-                    aiProvider: options.fakeAi ? 'fake' : (options.openAiApiKey ? 'openai' : ''),
-                    externalEffects: options.taskEnabled
-                }
-            });
-        });
-
-        socket.on('data', chunk => {
-            buffer += chunk;
-            let newlineIndex = buffer.indexOf('\n');
-            while (newlineIndex >= 0) {
-                const line = buffer.slice(0, newlineIndex).trim();
-                buffer = buffer.slice(newlineIndex + 1);
-                newlineIndex = buffer.indexOf('\n');
-                if (!line) {
-                    continue;
-                }
-
-                const message = JSON.parse(line);
-                if (message.type === 'welcome') {
-                    console.log(`Connected to LiveDesk Hub as ${options.name} (${deviceId})`);
-                    writeJsonLine(socket, {
-                        type: 'status',
-                        status: getStatus(options)
-                    });
-                    if (options.once) {
-                        finish();
-                        return;
-                    }
-
-                    heartbeatTimer = setInterval(() => {
-                        writeJsonLine(socket, {
-                            type: 'status',
-                            status: getStatus(options)
-                        });
-                    }, options.heartbeatMs);
-                } else if (message.type === 'command') {
-                    handleRemoteCommand(socket, options, message, () => {
-                        frameSeq += 1;
-                        return frameSeq;
-                    }, activeStreams).catch(error => {
-                        writeJsonLine(socket, {
-                            type: 'command.result',
-                            commandId: message.commandId,
-                            error: error?.message || String(error)
-                        });
-                    });
-                } else if (message.type === 'disconnect') {
-                    finish();
-                    return;
-                } else if (message.type === 'error') {
-                    const remoteError = new Error(message.error || 'LiveDesk Hub rejected the connection.');
-                    if (message.error === 'invalid-pair-token' && options.exitOnInvalidPair) {
-                        remoteError.exitCode = EXIT_INVALID_PAIR_TOKEN;
-                    }
-                    finish(remoteError);
-                    return;
-                }
-            }
-        });
-
-        socket.once('error', err => finish(err));
-        socket.once('close', () => finish());
-    });
-}
-
-async function connectWithRetry(options) {
-    if (!options.pair) {
-        throw new Error('Missing --pair token. Sign in with Google or get it from LiveDesk Hub status.');
-    }
-
-    const deviceId = await getDeviceId(options.deviceId);
-    let attempt = 0;
-    let stopping = false;
-
-    process.once('SIGINT', () => {
-        stopping = true;
-        console.log('\nStopping LiveDesk Client...');
-    });
-    process.once('SIGTERM', () => {
-        stopping = true;
-    });
-
-    while (!stopping) {
-        try {
-            await connectOnce(options, deviceId);
-            if (options.once || options.exitOnDisconnect || stopping) {
-                return;
-            }
-            attempt = 0;
-        } catch (err) {
-            attempt += 1;
-            if (err?.exitCode === EXIT_INVALID_PAIR_TOKEN) {
-                throw err;
-            }
-            const delayMs = DEFAULT_RECONNECT_MS;
-            console.error(`LiveDesk Hub connection failed: ${err?.message || err}. Retrying in ${delayMs}ms.`);
-            await wait(delayMs);
-        }
-    }
-}
-
-async function main() {
-    const options = parseArgs(process.argv.slice(2));
-    if (options.version || options.command === 'version') {
-        console.log(AGENT_VERSION);
-        return;
-    }
-
-    if (options.help || options.command === 'help') {
-        printHelp();
-        return;
-    }
-
-    if (options.command !== 'connect') {
-        throw new Error(`Unknown command: ${options.command}`);
-    }
-
-    await connectWithRetry(options);
-}
-
-main().catch(err => {
-    console.error(err?.message || err);
-    process.exit(Number.isInteger(err?.exitCode) ? err.exitCode : 1);
-});
+        }
+        return;
+    }
+
+    if (command === 'agent.task') {
+        if (!options.taskEnabled) {
+            writeJsonLine(socket, {
+                type: 'command.result',
+                commandId: message.commandId,
+                error: 'remote task capability is disabled'
+            });
+            return;
+        }
+
+        const payload = message.payload || {};
+        const instruction = String(payload.instruction || '').replace(/\0/g, '').trim().slice(0, 4000);
+        if (!instruction) {
+            writeJsonLine(socket, {
+                type: 'command.result',
+                commandId: message.commandId,
+                error: 'missing task instruction'
+            });
+            return;
+        }
+
+        const approvalLevel = normalizeApprovalLevel(payload.approvalLevel);
+        const completedAt = new Date().toISOString();
+        const title = String(payload.title || instruction.split(/\r?\n/)[0] || 'Remote task')
+            .replace(/[\r\n\t]/g, ' ')
+            .trim()
+            .slice(0, 120);
+        if (approvalLevel === 'ai-assist') {
+            try {
+                const aiResult = await runAiAssistTask(options, payload, instruction);
+                writeJsonLine(socket, {
+                    type: 'command.result',
+                    commandId: message.commandId,
+                    result: {
+                        kind: 'agent.task',
+                        mode: 'ai-assist',
+                        taskId: String(payload.taskId || '').slice(0, 128),
+                        title,
+                        status: 'completed',
+                        summary: aiResult.text,
+                        sideEffects: 'none',
+                        model: aiResult.model,
+                        responseId: aiResult.responseId,
+                        instructionPreview: instruction.slice(0, 320),
+                        completedAt: new Date().toISOString()
+                    }
+                });
+            } catch (error) {
+                writeJsonLine(socket, {
+                    type: 'command.result',
+                    commandId: message.commandId,
+                    error: error?.message || String(error)
+                });
+            }
+            return;
+        }
+
+        writeJsonLine(socket, {
+            type: 'command.result',
+            commandId: message.commandId,
+            result: {
+                kind: 'agent.task',
+                mode: 'task-only',
+                taskId: String(payload.taskId || '').slice(0, 128),
+                title,
+                status: 'completed',
+                summary: `Task received by ${options.name}. Safe task-only mode confirmed receipt without shell, file, input, or browser side effects.`,
+                sideEffects: 'none',
+                instructionPreview: instruction.slice(0, 320),
+                device: {
+                    hostname: os.hostname(),
+                    platform: os.platform(),
+                    release: os.release(),
+                    arch: os.arch()
+                },
+                completedAt
+            }
+        });
+        return;
+    }
+
+    if (command === 'thumbnail.capture') {
+        try {
+            const frameSeq = nextFrameSeq();
+            const frame = await captureThumbnailFrame(options, message.payload || {}, frameSeq);
+            writeJsonLine(socket, {
+                type: 'thumbnail.frame',
+                commandId: message.commandId,
+                streamId: message.payload?.streamId || 'thumbnail',
+                frameSeq: frame.frameSeq,
+                width: frame.width,
+                height: frame.height,
+                sourceWidth: frame.sourceWidth || frame.width,
+                sourceHeight: frame.sourceHeight || frame.height,
+                mimeType: frame.mimeType,
+                capturedAt: frame.capturedAt,
+                data: frame.data
+            });
+            writeJsonLine(socket, {
+                type: 'command.result',
+                commandId: message.commandId,
+                result: {
+                    thumbnail: true,
+                    frameSeq: frame.frameSeq,
+                    width: frame.width,
+                    height: frame.height,
+                    sourceWidth: frame.sourceWidth || frame.width,
+                    sourceHeight: frame.sourceHeight || frame.height,
+                    capturedAt: frame.capturedAt
+                }
+            });
+        } catch (error) {
+            writeJsonLine(socket, {
+                type: 'command.result',
+                commandId: message.commandId,
+                error: error?.message || String(error)
+            });
+        }
+        return;
+    }
+
+    if (command === 'stream.start') {
+        try {
+            const started = startLiveStream(socket, options, message, nextFrameSeq, activeStreams);
+            writeJsonLine(socket, {
+                type: 'command.result',
+                commandId: message.commandId,
+                result: {
+                    stream: true,
+                    started: true,
+                    streamId: started.streamId,
+                    fps: started.fps,
+                    intervalMs: started.intervalMs,
+                    mode: 'mode1-jpeg',
+                    viewOnly: true,
+                    inputControl: false,
+                    startedAt: new Date().toISOString()
+                }
+            });
+        } catch (error) {
+            writeJsonLine(socket, {
+                type: 'command.result',
+                commandId: message.commandId,
+                error: error?.message || String(error)
+            });
+        }
+        return;
+    }
+
+    if (command === 'stream.stop') {
+        const streamId = String(message.payload?.streamId || '').slice(0, 128);
+        const stopped = stopLiveStream(activeStreams, streamId);
+        writeJsonLine(socket, {
+            type: 'command.result',
+            commandId: message.commandId,
+            result: {
+                stream: true,
+                stopped: true,
+                streamId,
+                stoppedCount: stopped,
+                stoppedAt: new Date().toISOString()
+            }
+        });
+        return;
+    }
+
+    if (command === 'file.transfer') {
+        try {
+            const result = await handleFileTransferCommand(options, message.payload || {});
+            writeJsonLine(socket, {
+                type: 'command.result',
+                commandId: message.commandId,
+                result
+            });
+        } catch (error) {
+            writeJsonLine(socket, {
+                type: 'command.result',
+                commandId: message.commandId,
+                error: error?.message || String(error)
+            });
+        }
+        return;
+    }
+
+    if (command === 'file.transfer.chunk') {
+        try {
+            const result = await handleFileTransferChunkCommand(options, message.payload || {});
+            writeJsonLine(socket, {
+                type: 'command.result',
+                commandId: message.commandId,
+                result
+            });
+        } catch (error) {
+            writeJsonLine(socket, {
+                type: 'command.result',
+                commandId: message.commandId,
+                error: error?.message || String(error)
+            });
+        }
+        return;
+    }
+
+    if (command === 'audio.start' || command === 'audio.stop') {
+        writeJsonLine(socket, {
+            type: 'command.result',
+            commandId: message.commandId,
+            error: 'remote audio is only available in a RemoteFast engine with audio support'
+        });
+        return;
+    }
+
+    if (command === 'input.control') {
+        writeJsonLine(socket, {
+            type: 'command.result',
+            commandId: message.commandId,
+            error: 'input control is only available in the C# RemoteFast engine'
+        });
+        return;
+    }
+
+    writeJsonLine(socket, {
+        type: 'command.result',
+        commandId: message.commandId,
+        error: `Unsupported command: ${command}`
+    });
+}
+
+function connectOnce(options, deviceId) {
+    const manager = parseManagerAddress(options.manager);
+    return new Promise((resolve, reject) => {
+        const socket = net.createConnection({
+            host: manager.host,
+            port: manager.port
+        });
+
+        let buffer = '';
+        let heartbeatTimer = null;
+        let resolved = false;
+        let frameSeq = 0;
+        const activeStreams = new Map();
+
+        function cleanup() {
+            if (heartbeatTimer) {
+                clearInterval(heartbeatTimer);
+                heartbeatTimer = null;
+            }
+            stopLiveStream(activeStreams);
+        }
+
+        function finish(error = null) {
+            if (resolved) {
+                return;
+            }
+            resolved = true;
+            cleanup();
+            if (!socket.destroyed) {
+                socket.destroy();
+            }
+            if (error) {
+                reject(error);
+            } else {
+                resolve();
+            }
+        }
+
+        socket.setEncoding('utf8');
+        socket.setNoDelay(true);
+        socket.setKeepAlive(true, options.heartbeatMs);
+
+        socket.once('connect', () => {
+            writeJsonLine(socket, {
+                type: 'hello',
+                pairToken: options.pair,
+                deviceId,
+                deviceName: options.name,
+                slotNumber: options.slotNumber || undefined,
+                hostname: os.hostname(),
+                platform: os.platform(),
+                arch: os.arch(),
+                pid: process.pid,
+                agentVersion: AGENT_VERSION,
+                capabilities: {
+                    status: true,
+                    thumbnail: options.thumbnailEnabled,
+                    liveStream: options.liveEnabled,
+                    monitorSelection: true,
+                    screenCount: 1,
+                    monitorCount: 1,
+                    control: false,
+                    audio: false,
+                    remoteAudio: false,
+                    fileTransfer: true,
+                    remoteFiles: true,
+                    fileTransferMaxBytes: MAX_FILE_TRANSFER_BYTES,
+                    computerAgent: options.taskEnabled,
+                    taskDispatch: options.taskEnabled,
+                    agentApproval: options.taskEnabled,
+                    agentAudit: options.taskEnabled,
+                    agentTools: [...NODE_AGENT_OPERATIONS],
+                    elevation: typeof process.getuid === 'function' ? process.getuid() === 0 : false,
+                    aiAssist: options.taskEnabled && options.aiEnabled && (options.fakeAi || !!options.openAiApiKey),
+                    aiModel: options.aiModel,
+                    aiProvider: options.fakeAi ? 'fake' : (options.openAiApiKey ? 'openai' : ''),
+                    externalEffects: options.taskEnabled
+                }
+            });
+        });
+
+        socket.on('data', chunk => {
+            buffer += chunk;
+            let newlineIndex = buffer.indexOf('\n');
+            while (newlineIndex >= 0) {
+                const line = buffer.slice(0, newlineIndex).trim();
+                buffer = buffer.slice(newlineIndex + 1);
+                newlineIndex = buffer.indexOf('\n');
+                if (!line) {
+                    continue;
+                }
+
+                const message = JSON.parse(line);
+                if (message.type === 'welcome') {
+                    console.log(`Connected to LiveDesk Hub as ${options.name} (${deviceId})`);
+                    writeJsonLine(socket, {
+                        type: 'status',
+                        status: getStatus(options)
+                    });
+                    if (options.once) {
+                        finish();
+                        return;
+                    }
+
+                    heartbeatTimer = setInterval(() => {
+                        writeJsonLine(socket, {
+                            type: 'status',
+                            status: getStatus(options)
+                        });
+                    }, options.heartbeatMs);
+                } else if (message.type === 'command') {
+                    handleRemoteCommand(socket, options, message, () => {
+                        frameSeq += 1;
+                        return frameSeq;
+                    }, activeStreams).catch(error => {
+                        writeJsonLine(socket, {
+                            type: 'command.result',
+                            commandId: message.commandId,
+                            error: error?.message || String(error)
+                        });
+                    });
+                } else if (message.type === 'disconnect') {
+                    finish();
+                    return;
+                } else if (message.type === 'error') {
+                    const remoteError = new Error(message.error || 'LiveDesk Hub rejected the connection.');
+                    if (message.error === 'invalid-pair-token' && options.exitOnInvalidPair) {
+                        remoteError.exitCode = EXIT_INVALID_PAIR_TOKEN;
+                    }
+                    finish(remoteError);
+                    return;
+                }
+            }
+        });
+
+        socket.once('error', err => finish(err));
+        socket.once('close', () => finish());
+    });
+}
+
+async function connectWithRetry(options) {
+    if (!options.pair) {
+        throw new Error('Missing --pair token. Sign in with Google or get it from LiveDesk Hub status.');
+    }
+
+    const deviceId = await getDeviceId(options.deviceId);
+    let attempt = 0;
+    let stopping = false;
+
+    process.once('SIGINT', () => {
+        stopping = true;
+        console.log('\nStopping LiveDesk Client...');
+    });
+    process.once('SIGTERM', () => {
+        stopping = true;
+    });
+
+    while (!stopping) {
+        try {
+            await connectOnce(options, deviceId);
+            if (options.once || options.exitOnDisconnect || stopping) {
+                return;
+            }
+            attempt = 0;
+        } catch (err) {
+            attempt += 1;
+            if (err?.exitCode === EXIT_INVALID_PAIR_TOKEN) {
+                throw err;
+            }
+            const delayMs = DEFAULT_RECONNECT_MS;
+            console.error(`LiveDesk Hub connection failed: ${err?.message || err}. Retrying in ${delayMs}ms.`);
+            await wait(delayMs);
+        }
+    }
+}
+
+async function main() {
+    const options = parseArgs(process.argv.slice(2));
+    if (options.version || options.command === 'version') {
+        console.log(AGENT_VERSION);
+        return;
+    }
+
+    if (options.help || options.command === 'help') {
+        printHelp();
+        return;
+    }
+
+    if (options.command !== 'connect') {
+        throw new Error(`Unknown command: ${options.command}`);
+    }
+
+    await connectWithRetry(options);
+}
+
+main().catch(err => {
+    console.error(err?.message || err);
+    process.exit(Number.isInteger(err?.exitCode) ? err.exitCode : 1);
+});