@livedesk/hub 0.1.61 → 0.1.65

package/src/remote-hub.js

@@ -56,9 +56,13 @@ const MAX_AGENT_SOCKET_ACCUMULATOR_BYTES = MAX_LINE_CHARS
 const HTTP_HEADER_TERMINATOR = Buffer.from('\r\n\r\n', 'ascii');
 const MAX_AGENT_TASK_CHARS = 4000;
 const MAX_AGENT_TASK_RESULT_CHARS = 3000;
-const MAX_AGENT_TASK_DATA_CHARS = 64 * 1024;
-const RECENT_TASK_LIMIT = 12;
-const RECENT_TASK_BATCH_LIMIT = 16;
+const MAX_AGENT_TASK_DATA_BYTES = 64 * 1024;
+const MAX_AGENT_TASK_PREVIEW_BYTES = 16 * 1024;
+const MAX_AGENT_TOOL_ARGUMENTS_BYTES = 24 * 1024;
+const RECENT_TASK_LIMIT = 12;
+const MAX_PENDING_AGENT_TASKS_PER_DEVICE = RECENT_TASK_LIMIT;
+const RECENT_TASK_BATCH_LIMIT = 16;
+const MAX_AGENT_SOCKET_WRITE_BUFFER_BYTES = MAX_LINE_CHARS + (256 * 1024);
 const RECENT_FRAME_CACHE_TTL_MS = 4000;
 const RECENT_THUMBNAIL_FRAME_CACHE_LIMIT = 2;
 const RECENT_LIVE_FRAME_CACHE_LIMIT = 1;
@@ -68,6 +72,7 @@ const LIVE_STREAM_PENDING_REUSE_MS = 5000;
 const LIVE_STREAM_REPLACEMENT_PENDING_MS = 7000;
 const LIVE_STREAM_MIN_FRESH_MS = 3000;
 const LIVE_STREAM_MAX_FRESH_MS = 12000;
+const TASK_BATCH_OWNER = Symbol('remote-hub-task-batch-owner');
 const DEFAULT_REMOTE_INPUT_ACK_TIMEOUT_MS = 5000;
 // RemoteFast owns a shared 7s native stop deadline. Keep four seconds for a
 // priority command.result to cross either Direct or encrypted Relay transport.
@@ -305,9 +310,17 @@ function normalizePort(value) {
     return clampNumber(value, 0, 65535, DEFAULT_REMOTE_HUB_PORT);
 }
 
-function safeString(value, maxLength = 200) {
-    return String(value ?? '').replace(/[\r\n\t]/g, ' ').trim().slice(0, maxLength);
-}
+function safeString(value, maxLength = 200) {
+    return String(value ?? '').replace(/[\r\n\t]/g, ' ').trim().slice(0, maxLength);
+}
+
+export function normalizeMediaBinaryKind(value) {
+    if (typeof value !== 'string' || value.length > 64) {
+        return '';
+    }
+    const normalized = value.trim().toLowerCase();
+    return normalized.length <= 40 ? normalized : '';
+}
 
 function remoteInputPayloadType(payload) {
     return safeString(payload?.payload?.type ?? payload?.type, 48).toLowerCase();
@@ -1224,16 +1237,131 @@ function normalizeRemoteKeyboardText(value) {
     return raw.slice(0, 256);
 }
 
-function safeTaskData(value) {
-    if (value === undefined || value === null) return undefined;
-    try {
-        const serialized = JSON.stringify(value);
-        if (serialized.length <= MAX_AGENT_TASK_DATA_CHARS) return value;
-        return { truncated: true, byteLength: Buffer.byteLength(serialized, 'utf8'), preview: serialized.slice(0, MAX_AGENT_TASK_DATA_CHARS) };
-    } catch {
-        return { truncated: true };
-    }
-}
+function utf8Prefix(value, maxBytes) {
+    const text = String(value ?? '');
+    const encoded = Buffer.from(text, 'utf8');
+    if (encoded.length <= maxBytes) {
+        return text;
+    }
+    let end = Math.max(0, Math.min(encoded.length, Math.floor(maxBytes)));
+    while (end > 0 && end < encoded.length && (encoded[end] & 0xc0) === 0x80) {
+        end -= 1;
+    }
+    return encoded.subarray(0, end).toString('utf8');
+}
+
+function boundedSerializedTaskData(serialized) {
+    const byteLength = Buffer.byteLength(serialized, 'utf8');
+    if (byteLength <= MAX_AGENT_TASK_DATA_BYTES) {
+        return JSON.parse(serialized);
+    }
+    return {
+        truncated: true,
+        byteLength,
+        preview: utf8Prefix(serialized, MAX_AGENT_TASK_PREVIEW_BYTES)
+    };
+}
+
+function safeTaskData(value) {
+    if (value === undefined || value === null) return undefined;
+    try {
+        const serialized = JSON.stringify(value);
+        return serialized === undefined ? undefined : boundedSerializedTaskData(serialized);
+    } catch {
+        return { truncated: true };
+    }
+}
+
+function isPlainObject(value) {
+    if (!value || typeof value !== 'object' || Array.isArray(value)) {
+        return false;
+    }
+    const prototype = Object.getPrototypeOf(value);
+    return prototype === Object.prototype || prototype === null;
+}
+
+const DIAGNOSTIC_AGENT_OPERATIONS = new Set(['logs.collect', 'diagnostics.collect']);
+const DIAGNOSTIC_LOG_SOURCES = new Set(['vuvodesk', 'system']);
+const DIAGNOSTIC_SENSITIVE_KEY = /(?:token|secret|password|passwd|api[-_]?key|authorization|private[-_]?key|connection[-_]?string|access[-_]?key|credential|cookie|pair)/i;
+const DIAGNOSTIC_STANDALONE_SECRET_VALUE = /\b(?:sk-(?:proj-|ant-(?:api\d{2}-)?)?[A-Za-z0-9_-]{16,}|gh[pousr]_[A-Za-z0-9]{20,}|github_pat_[A-Za-z0-9_]{20,}|(?:AKIA|ASIA)[A-Z0-9]{16}|AIza[A-Za-z0-9_-]{20,}|npm_[A-Za-z0-9]{20,}|xox[A-Za-z]-[A-Za-z0-9-]{10,}|[sr]k_(?:live|test)_[A-Za-z0-9]{10,})\b/g;
+
+function redactDiagnosticText(value) {
+    let text = String(value ?? '').replace(/\0/g, '');
+    text = text.replace(
+        /-----BEGIN(?: [A-Z0-9]+)* PRIVATE KEY-----[\s\S]*?-----END(?: [A-Z0-9]+)* PRIVATE KEY-----/gi,
+        '[redacted-private-key]');
+    text = text.replace(/\b(?:Proxy-)?Authorization\s*[:=]\s*[^\r\n]*/gi, 'Authorization: [redacted]');
+    text = text.replace(/\b(?:Set-)?Cookie\s*[:=]\s*[^\r\n]*/gi, 'Cookie: [redacted]');
+    text = text.replace(/\b(?:Bearer|Basic)\s+[A-Za-z0-9._~+/=-]+/gi, '[redacted-authorization]');
+    text = text.replace(DIAGNOSTIC_STANDALONE_SECRET_VALUE, '[redacted-secret]');
+    text = text.replace(/\b(?:eyJ)?[A-Za-z0-9_-]{8,}\.[A-Za-z0-9_-]{8,}\.[A-Za-z0-9_-]{8,}\b/g, '[redacted-jwt]');
+    text = text.replace(
+        /(^|[\s,;?&])([A-Za-z0-9_.-]*(?:token|secret|password|passwd|api[-_]?key|authorization|private[-_]?key|connection[-_]?string|access[-_]?key|credential|cookie|pair)[A-Za-z0-9_.-]*)\s*[:=]\s*(?:"[^"]*"|'[^']*'|[^\s,;&#]+)/gi,
+        '$1$2=[redacted]');
+    return text;
+}
+
+function diagnosticJsonReplacer(key, value) {
+    if (key && DIAGNOSTIC_SENSITIVE_KEY.test(key)) {
+        return '[redacted]';
+    }
+    return typeof value === 'string' ? redactDiagnosticText(value) : value;
+}
+
+function safeDiagnosticText(value, maxBytes) {
+    return utf8Prefix(redactDiagnosticText(value), maxBytes).trim();
+}
+
+function safeDiagnosticTaskData(value) {
+    if (value === undefined || value === null) return undefined;
+    try {
+        const serialized = JSON.stringify(value, diagnosticJsonReplacer);
+        return serialized === undefined ? undefined : boundedSerializedTaskData(serialized);
+    } catch {
+        return { truncated: true };
+    }
+}
+
+function normalizeAgentToolArguments(operation, value) {
+    const candidate = value === undefined || value === null ? {} : value;
+    if (!isPlainObject(candidate)) {
+        return { ok: false, error: 'invalid-tool-arguments' };
+    }
+    try {
+        const serialized = JSON.stringify(candidate);
+        if (serialized === undefined || Buffer.byteLength(serialized, 'utf8') > MAX_AGENT_TOOL_ARGUMENTS_BYTES) {
+            return { ok: false, error: 'tool-arguments-too-large' };
+        }
+        const cloned = JSON.parse(serialized);
+        if (!isPlainObject(cloned)) {
+            return { ok: false, error: 'invalid-tool-arguments' };
+        }
+        if (DIAGNOSTIC_AGENT_OPERATIONS.has(operation)) {
+            const requestedSource = safeString(cloned.source, 40).toLowerCase();
+            return {
+                ok: true,
+                value: {
+                    source: DIAGNOSTIC_LOG_SOURCES.has(requestedSource) ? requestedSource : 'vuvodesk',
+                    maxLines: clampNumber(cloned.maxLines, 1, 500, 100)
+                }
+            };
+        }
+        return { ok: true, value: cloned };
+    } catch {
+        return { ok: false, error: 'invalid-tool-arguments' };
+    }
+}
+
+function safeRetryToolArguments(operation, value) {
+    const normalized = normalizeAgentToolArguments(operation, value);
+    return normalized.ok ? normalized.value : {};
+}
+
+function normalizeAgentPermissionMode(operation, value) {
+    return DIAGNOSTIC_AGENT_OPERATIONS.has(operation)
+        ? 'safe-auto'
+        : safeString(value, 40) || 'ask';
+}
 
 function normalizeApprovalLevel(value) {
     const level = safeString(value, 80).toLowerCase();
@@ -1282,10 +1410,20 @@ const SUPPORTED_AGENT_OPERATIONS = new Set([
     'logs.collect'
 ]);
 
-function normalizeAgentOperation(value) {
+function normalizeAgentOperation(value) {
     const operation = safeString(value, 80).toLowerCase();
     return SUPPORTED_AGENT_OPERATIONS.has(operation) ? operation : '';
-}
+}
+
+function deviceSupportsAgentOperation(device, operation) {
+    const advertised = device?.capabilities?.agentTools;
+    if (!Array.isArray(advertised)) {
+        // Older Clients did not advertise the list. Keep their established
+        // behavior, but fail closed whenever a Client provides an exact list.
+        return true;
+    }
+    return advertised.some(value => safeString(value, 80) === operation);
+}
 
 const REMOTE_INPUT_MONITOR_KEYS = Object.freeze([
     'monitorIndex',
@@ -1661,7 +1799,23 @@ function findRecentFramePayload(device, frameKind, options = {}) {
     return entry?.frame || null;
 }
 
-function serializeDevice(device, options = {}) {
+function serializeDeviceTask(task) {
+    if (!task) {
+        return null;
+    }
+    const publicTask = { ...task };
+    const resultData = publicTask.resultData;
+    delete publicTask.resultData;
+    delete publicTask.toolArguments;
+    delete publicTask.retryToolArguments;
+    delete publicTask.retryPermissionMode;
+    return {
+        ...publicTask,
+        hasResultData: resultData !== undefined && resultData !== null
+    };
+}
+
+function serializeDevice(device, options = {}) {
     if (!device) {
         return null;
     }
@@ -1736,17 +1890,17 @@ function serializeDevice(device, options = {}) {
         latestAudioStatus: device.latestAudioStatus ? { ...device.latestAudioStatus } : null,
         clientUpdateProof: device.clientUpdateProof ? { ...device.clientUpdateProof } : null,
         udp: device.udp ? { ...device.udp } : { enabled: false, state: 'tcp-only', ready: false },
-        latestTask: device.latestTask ? { ...device.latestTask } : null,
+        latestTask: serializeDeviceTask(device.latestTask),
         synthetic: device.synthetic === true,
         recentTasks: Array.isArray(device.recentTasks)
-            ? device.recentTasks.map(task => ({ ...task }))
+            ? device.recentTasks.map(serializeDeviceTask).filter(Boolean)
             : [],
         status: { ...device.status },
         counters: { ...device.counters }
     };
 }
 
-function serializeTaskBatch(batch) {
+function serializeTaskBatch(batch, options = {}) {
     if (!batch) {
         return null;
     }
@@ -1768,24 +1922,51 @@ function serializeTaskBatch(batch) {
         failed: batch.failed,
         cancelled: batch.cancelled,
         timedOut: batch.timedOut,
-        results: Array.isArray(batch.results)
-            ? batch.results.map(item => ({ ...item }))
-            : []
+        results: Array.isArray(batch.results)
+            ? batch.results.map(item => {
+                const { data, ...publicItem } = item;
+                return options.includeData === true
+                    ? {
+                        ...publicItem,
+                        hasResultData: data !== undefined && data !== null,
+                        data: safeTaskData(data)
+                    }
+                    : {
+                        ...publicItem,
+                        hasResultData: data !== undefined && data !== null
+                    };
+            })
+            : []
     };
 }
 
-function writeJsonLine(socket, payload) {
+function writeJsonLine(socket, payload) {
     if (!socket || socket.destroyed) {
         return false;
     }
 
-    if (socket.__remoteHubWebSocket === true && typeof socket.sendJson === 'function') {
-        return socket.sendJson(payload);
-    }
-
-    socket.write(`${JSON.stringify(payload)}\n`);
-    return true;
-}
+    if (socket.__remoteHubWebSocket === true && typeof socket.sendJson === 'function') {
+        return socket.sendJson(payload);
+    }
+
+    try {
+        const line = Buffer.from(`${JSON.stringify(payload)}\n`, 'utf8');
+        const bufferedBytes = Math.max(0, Number(socket.writableLength || 0));
+        if (bufferedBytes + line.length > MAX_AGENT_SOCKET_WRITE_BUFFER_BYTES) {
+            socket.destroy();
+            return false;
+        }
+
+        // net.Socket.write(false) means the bytes were accepted into Node's
+        // writable queue. Keep that accepted write successful, but never allow
+        // later writes to grow the queue past the fixed byte cap above.
+        socket.write(line);
+        return true;
+    } catch {
+        socket.destroy();
+        return false;
+    }
+}
 
 function writeJsonLineAndClose(socket, payload) {
     if (!socket || socket.destroyed) {
@@ -2050,16 +2231,26 @@ export class RemoteHubWebSocketAgentSocket {
         return this.sendFrame(0x1, Buffer.from(String(text || ''), 'utf8'));
     }
 
-    sendFrame(opcode, payload) {
-        if (this.destroyed || this.socket.destroyed) {
-            return false;
-        }
-
-        try {
-            return this.socket.write(buildRemoteHubWebSocketFrame(opcode, payload)) !== false;
-        } catch {
-            this.destroy();
-            return false;
+    sendFrame(opcode, payload) {
+        if (this.destroyed || this.socket.destroyed) {
+            return false;
+        }
+
+        try {
+            const frame = buildRemoteHubWebSocketFrame(opcode, payload);
+            const bufferedBytes = Math.max(0, Number(this.socket?.writableLength || 0));
+            if (bufferedBytes + frame.length > MAX_AGENT_SOCKET_WRITE_BUFFER_BYTES) {
+                this.destroy();
+                return false;
+            }
+
+            // The raw socket owns a single bounded queue for every WebSocket
+            // message. A false return still means this exact frame was queued.
+            this.socket.write(frame);
+            return true;
+        } catch {
+            this.destroy();
+            return false;
         }
     }
 
@@ -2370,13 +2561,18 @@ export function createRemoteHub(options = {}) {
             defaultDeviceConnectionStaleMs,
             10 * 60 * 1000,
             defaultDeviceConnectionStaleMs);
-    const deviceConnectionSweepMs = Number.isFinite(Number(options.deviceConnectionSweepMs))
-        ? clampNumber(options.deviceConnectionSweepMs, 25, 60000, DEFAULT_DEVICE_CONNECTION_SWEEP_MS)
-        : clampNumber(
-            env.REMOTE_HUB_DEVICE_CONNECTION_SWEEP_MS,
-            1000,
-            60000,
-            Math.min(DEFAULT_DEVICE_CONNECTION_SWEEP_MS, heartbeatMs));
+    const deviceConnectionSweepMs = Number.isFinite(Number(options.deviceConnectionSweepMs))
+        ? clampNumber(options.deviceConnectionSweepMs, 25, 60000, DEFAULT_DEVICE_CONNECTION_SWEEP_MS)
+        : clampNumber(
+            env.REMOTE_HUB_DEVICE_CONNECTION_SWEEP_MS,
+            1000,
+            60000,
+            Math.min(DEFAULT_DEVICE_CONNECTION_SWEEP_MS, heartbeatMs));
+    const udpStartRetryInitialMs = clampNumber(
+        options.udpStartRetryMs ?? env.LIVEDESK_UDP_START_RETRY_MS,
+        250,
+        60000,
+        5000);
     const taskTimeoutMs = clampNumber(
         options.taskTimeoutMs ?? env.REMOTE_HUB_TASK_TIMEOUT_MS,
         50,
@@ -2415,13 +2611,14 @@ export function createRemoteHub(options = {}) {
         false);
     const relayControl = options.relayControl && typeof options.relayControl === 'object'
         ? options.relayControl
-        : createHubRelayControl({
-            env,
-            pairToken,
-            logEvent,
-            logWarn,
-            onPeerSocket: socket => handleTcpAgentSocket(socket)
-        });
+        : createHubRelayControl({
+            env,
+            pairToken,
+            logEvent,
+            logWarn,
+            retiredPayloadRelayTestOnly: options.retiredPayloadRelayTestOnly === true,
+            onPeerSocket: socket => handleTcpAgentSocket(socket)
+        });
     let pairingPin = /^\d{6}$/.test(String(options.pairingPin || env.LIVEDESK_PAIRING_PIN || '').trim())
         ? String(options.pairingPin || env.LIVEDESK_PAIRING_PIN).trim()
         : generatePairingPin();
@@ -2450,11 +2647,15 @@ export function createRemoteHub(options = {}) {
     const clipboardOperations = new Map();
     const transportDiagnostics = new Map();
     const transportDiagnosticStartingDevices = new Set();
-    const duplicateDeviceLogAt = new Map();
-    let server = null;
-    let started = false;
-    let deviceConnectionSweepTimer = null;
-    let boundPort = requestedPort;
+    const duplicateDeviceLogAt = new Map();
+    let server = null;
+    let started = false;
+    let closing = false;
+    let deviceConnectionSweepTimer = null;
+    let udpStartRetryTimer = null;
+    let udpStartRetryDelayMs = udpStartRetryInitialMs;
+    let udpStartPromise = null;
+    let boundPort = requestedPort;
     let lastError = '';
     let hostTarget = null;
     let publicIPv4Cache = {
@@ -2763,12 +2964,20 @@ export function createRemoteHub(options = {}) {
         const activeHostTarget = serializeHostTarget();
         const routeInfo = getAgentEndpointRouteInfo();
         const diagnostics = sampleHubRuntimeDiagnostics();
-        diagnostics.network = {
-            lanDeviceCount: connectedRoutes.length - externalDeviceCount,
-            externalDeviceCount,
-            route: externalDeviceCount > 0 ? 'external' : connectedRoutes.length > 0 ? 'lan' : 'idle'
-        };
-        return {
+        diagnostics.network = {
+            lanDeviceCount: connectedRoutes.length - externalDeviceCount,
+            externalDeviceCount,
+            route: externalDeviceCount > 0 ? 'external' : connectedRoutes.length > 0 ? 'lan' : 'idle'
+        };
+        const udpStatus = udpTransport?.getStatus?.() || {
+            enabled: false,
+            preferred: false,
+            started: false,
+            port: 0,
+            sessionCount: 0,
+            readySessionCount: 0
+        };
+        return {
             enabled,
             started,
             host,
@@ -2812,14 +3021,14 @@ export function createRemoteHub(options = {}) {
             publicIPv4Address: publicIPv4Cache.address,
             publicIPv4UpdatedAt: publicIPv4Cache.updatedAt ? new Date(publicIPv4Cache.updatedAt).toISOString() : '',
             publicIPv4Error: publicIPv4Cache.error,
-            udp: udpTransport?.getStatus?.() || {
-                enabled: false,
-                preferred: false,
-                started: false,
-                port: 0,
-                sessionCount: 0,
-                readySessionCount: 0
-            },
+            udp: {
+                ...udpStatus,
+                startRetryTimerActive: udpStartRetryTimer !== null,
+                startInFlight: udpStartPromise !== null,
+                startRetryDelayMs: udpStartRetryTimer !== null
+                    ? udpStartRetryDelayMs
+                    : 0
+            },
             relay: relayControl?.getStatus?.() || {
                 enabled: false,
                 started: false,
@@ -2918,8 +3127,8 @@ export function createRemoteHub(options = {}) {
         return listTaskBatches()[0] || null;
     }
 
-    function getTaskBatch(batchId) {
-        return serializeTaskBatch(taskBatches.get(safeString(batchId, 128)) || null);
+    function getTaskBatch(batchId) {
+        return serializeTaskBatch(taskBatches.get(safeString(batchId, 128)) || null, { includeData: true });
     }
 
     function cancelTaskBatch(batchId) {
@@ -2974,12 +3183,14 @@ export function createRemoteHub(options = {}) {
         if (targetIds.length === 0) {
             return { ok: false, error: 'no-retry-targets' };
         }
-        return requestAgentTaskBatch(targetIds, {
-            instruction: batch.instructionPreview,
-            title: batch.title,
-            operation: batch.operation,
-            targetQuery: batch.targetQuery,
-            approvalLevel: batch.approvalLevel
+        return requestAgentTaskBatch(targetIds, {
+            instruction: batch.instructionPreview,
+            title: batch.title,
+            operation: batch.operation,
+            targetQuery: batch.targetQuery,
+            approvalLevel: batch.approvalLevel,
+            toolArguments: batch.retryToolArguments,
+            permissionMode: batch.retryPermissionMode
         });
     }
 
@@ -3014,18 +3225,20 @@ export function createRemoteHub(options = {}) {
         }
     }
 
-    function settlePendingCommandResult(device, message = {}) {
-        const commandId = safeString(message.commandId, 128);
+    function settlePendingCommandResult(device, message = {}, channel = 'control') {
+        channel = safeString(channel, 24) || 'control';
+        const commandId = safeString(message.commandId, 128);
         const waiterKey = buildPendingCommandResultWaiterKey(
             device?.deviceId,
             device?.sessionId,
             commandId);
         const waiter = pendingCommandResultWaiters.get(waiterKey);
-        if (!waiter
-            || waiter.deviceId !== device?.deviceId
-            || waiter.sessionId !== device?.sessionId) {
-            return false;
-        }
+        if (!waiter
+            || waiter.deviceId !== device?.deviceId
+            || waiter.sessionId !== device?.sessionId
+            || (safeString(waiter.channel, 24) || 'control') !== channel) {
+            return false;
+        }
 
         pendingCommandResultWaiters.delete(waiterKey);
         clearPendingCommandResultWaiterDeadline(waiter);
@@ -4821,7 +5034,107 @@ export function createRemoteHub(options = {}) {
         };
     }
 
-    function attachDevice(socket, hello) {
+    function registerCurrentDeviceUdpSession(device) {
+        const socket = device?.socket;
+        if (!device?.connected
+            || !socket
+            || socket.destroyed
+            || devices.get(device.deviceId) !== device) {
+            return null;
+        }
+        if (device.udp?.sessionId) {
+            return device.udp;
+        }
+        const sessionId = device.sessionId;
+        const udpSession = udpTransport?.registerDevice?.({
+            deviceId: device.deviceId,
+            sessionId,
+            sendControl: payload => {
+                if (devices.get(device.deviceId) === device
+                    && device.sessionId === sessionId
+                    && device.socket === socket
+                    && !socket.destroyed) {
+                    writeJsonLine(socket, payload);
+                }
+            },
+            capabilities: device.capabilities
+        });
+        if (devices.get(device.deviceId) !== device
+            || device.sessionId !== sessionId
+            || device.socket !== socket
+            || socket.destroyed) {
+            udpTransport?.unregisterDevice?.(device.deviceId, sessionId);
+            return null;
+        }
+        if (udpSession?.sessionId) {
+            device.udp = {
+                ...device.udp,
+                state: 'udp-session-created',
+                sessionId: udpSession.sessionId
+            };
+        }
+        return udpSession || null;
+    }
+
+    function scheduleOptionalUdpStartRetry() {
+        if (closing
+            || !started
+            || udpStartRetryTimer
+            || udpTransport?.getStatus?.().enabled === false) {
+            return;
+        }
+        const delayMs = udpStartRetryDelayMs;
+        udpStartRetryTimer = setTimeout(() => {
+            udpStartRetryTimer = null;
+            udpStartRetryDelayMs = Math.min(30000, delayMs * 2);
+            void startOptionalUdpTransport('retry');
+        }, delayMs);
+        udpStartRetryTimer.unref?.();
+    }
+
+    function startOptionalUdpTransport(reason) {
+        if (!udpTransport?.start
+            || udpTransport?.getStatus?.().enabled === false
+            || closing
+            || !started) {
+            return Promise.resolve(false);
+        }
+        if (udpStartPromise) {
+            return udpStartPromise;
+        }
+
+        const run = Promise.resolve().then(async () => {
+            try {
+                await udpTransport.start();
+                if (closing || !started) {
+                    return false;
+                }
+                udpStartRetryDelayMs = udpStartRetryInitialMs;
+                for (const device of devices.values()) {
+                    registerCurrentDeviceUdpSession(device);
+                }
+                return true;
+            } catch (error) {
+                if (!closing && started) {
+                    logWarn(
+                        'udp',
+                        `UDP P2P could not start (${reason}); Direct TCP remains available: ${error?.message || error}`);
+                    scheduleOptionalUdpStartRetry();
+                }
+                return false;
+            }
+        });
+        let owner = null;
+        owner = run.finally(() => {
+            if (udpStartPromise === owner) {
+                udpStartPromise = null;
+            }
+        });
+        udpStartPromise = owner;
+        return owner;
+    }
+
+    function attachDevice(socket, hello) {
         const nowMs = Date.now();
         const now = new Date(nowMs).toISOString();
         const sessionId = crypto.randomUUID();
@@ -4947,19 +5260,7 @@ export function createRemoteHub(options = {}) {
             serverTime: now
         });
 
-        const udpSession = udpTransport?.registerDevice?.({
-            deviceId,
-            sessionId,
-            sendControl: payload => writeJsonLine(socket, payload),
-            capabilities
-        });
-        if (udpSession?.sessionId) {
-            device.udp = {
-                ...device.udp,
-                state: 'udp-session-created',
-                sessionId: udpSession.sessionId
-            };
-        }
+        registerCurrentDeviceUdpSession(device);
 
         logEvent('remote', `device connected ${device.deviceName} (${deviceId})`, 'success');
         emitRemoteEvent('RemoteDeviceConnected', device);
@@ -5049,16 +5350,26 @@ export function createRemoteHub(options = {}) {
         return device;
     }
 
-    function attachFrameSocket(socket, hello) {
-        const deviceId = normalizeDeviceId(hello.deviceId);
-        const device = devices.get(deviceId);
-        if (!device || !device.connected || !device.socket || device.socket.destroyed) {
-            writeJsonLine(socket, { type: 'error', error: 'device-not-connected' });
-            socket.destroy();
-            return null;
-        }
-
-        closeFrameSocket(device, 'replaced-by-new-frame-socket');
+    function attachFrameSocket(socket, hello) {
+        const deviceId = normalizeDeviceId(hello.deviceId);
+        const device = devices.get(deviceId);
+        if (!device || !device.connected || !device.socket || device.socket.destroyed) {
+            writeJsonLine(socket, { type: 'error', error: 'device-not-connected' });
+            socket.destroy();
+            return null;
+        }
+        const parentSessionId = safeString(hello.parentSessionId, 160);
+        const requiresSessionBoundMedia = device.capabilities?.sessionBoundMediaChannels === true;
+        if ((parentSessionId && parentSessionId !== safeString(device.sessionId, 160))
+            || (!parentSessionId && requiresSessionBoundMedia)) {
+            writeJsonLineAndClose(socket, { type: 'error', error: 'side-channel-parent-session-stale' });
+            return null;
+        }
+        if (!parentSessionId) {
+            emitRemoteEvent('RemoteLegacyMediaSideChannelAccepted', device, { channel: 'frame' });
+        }
+
+        closeFrameSocket(device, 'replaced-by-new-frame-socket');
 
         const now = new Date().toISOString();
         device.frameSocket = socket;
@@ -5082,16 +5393,26 @@ export function createRemoteHub(options = {}) {
         return device;
     }
 
-    function attachAudioSocket(socket, hello) {
-        const deviceId = normalizeDeviceId(hello.deviceId);
-        const device = devices.get(deviceId);
-        if (!device || !device.connected || !device.socket || device.socket.destroyed) {
-            writeJsonLine(socket, { type: 'error', error: 'device-not-connected' });
-            socket.destroy();
-            return null;
-        }
-
-        closeAudioSocket(device, 'replaced-by-new-audio-socket');
+    function attachAudioSocket(socket, hello) {
+        const deviceId = normalizeDeviceId(hello.deviceId);
+        const device = devices.get(deviceId);
+        if (!device || !device.connected || !device.socket || device.socket.destroyed) {
+            writeJsonLine(socket, { type: 'error', error: 'device-not-connected' });
+            socket.destroy();
+            return null;
+        }
+        const parentSessionId = safeString(hello.parentSessionId, 160);
+        const requiresSessionBoundMedia = device.capabilities?.sessionBoundMediaChannels === true;
+        if ((parentSessionId && parentSessionId !== safeString(device.sessionId, 160))
+            || (!parentSessionId && requiresSessionBoundMedia)) {
+            writeJsonLineAndClose(socket, { type: 'error', error: 'side-channel-parent-session-stale' });
+            return null;
+        }
+        if (!parentSessionId) {
+            emitRemoteEvent('RemoteLegacyMediaSideChannelAccepted', device, { channel: 'audio' });
+        }
+
+        closeAudioSocket(device, 'replaced-by-new-audio-socket');
         const now = new Date().toISOString();
         device.audioSocket = socket;
         device.audioConnectedAt = now;
@@ -5158,8 +5479,10 @@ export function createRemoteHub(options = {}) {
         device.socket = null;
         abortTransportDiagnosticsForDevice(device, reason);
         udpTransport?.unregisterDevice?.(deviceId, device.sessionId);
-        closeInputSocket(device, reason);
-        closeFrameSocket(device, reason);
+        closeInputSocket(device, reason);
+        closeFrameSocket(device, reason);
+        closeAudioSocket(device, reason);
+        closeFileSocket(device, reason);
         device.disconnectedAt = new Date().toISOString();
         device.lastDisconnectReason = reason;
         deactivateDeviceLiveStreams(device, reason, device.disconnectedAt);
@@ -5171,10 +5494,10 @@ export function createRemoteHub(options = {}) {
         emitRemoteEvent('RemoteDeviceDisconnected', device, { reason });
     }
 
-    function rememberDeviceTask(device, task) {
-        if (!device || !task) {
-            return null;
-        }
+    function rememberDeviceTask(device, task) {
+        if (!device || !task) {
+            return null;
+        }
 
         const existingIndex = device.recentTasks.findIndex(item =>
             item.taskId === task.taskId || item.commandId === task.commandId);
@@ -5187,13 +5510,85 @@ export function createRemoteHub(options = {}) {
             device.recentTasks.length = RECENT_TASK_LIMIT;
         }
 
-        device.latestTask = task;
-        if (task.commandId) {
-            device.pendingTaskCommands.set(task.commandId, task);
-        }
+        device.latestTask = task;
+        if (task.commandId) {
+            device.pendingTaskCommands.set(task.commandId, task);
+        }
 
-        return task;
-    }
+        return task;
+    }
+
+    function markOwnedTaskBatch(batch) {
+        Object.defineProperty(batch, TASK_BATCH_OWNER, {
+            value: true,
+            enumerable: false,
+            configurable: false,
+            writable: false
+        });
+        return batch;
+    }
+
+    function getOwnedTaskBatch(options = {}) {
+        const batch = options.taskBatch;
+        if (!batch
+            || batch[TASK_BATCH_OWNER] !== true
+            || taskBatches.get(batch.batchId) !== batch) {
+            return null;
+        }
+        return batch;
+    }
+
+    function createAgentTaskOwner(device, taskId, commandId, operation, batchId = '') {
+        return Object.freeze({
+            deviceId: safeString(device?.deviceId, 160),
+            sessionId: safeString(device?.sessionId, 160),
+            taskId: safeString(taskId, 128),
+            commandId: safeString(commandId, 128),
+            operation: safeString(operation, 80),
+            batchId: safeString(batchId, 128)
+        });
+    }
+
+    function isPendingAgentTaskOwner(device, task, commandId) {
+        const owner = task?.owner;
+        const expectedCommandId = safeString(commandId, 128);
+        return !!owner
+            && device?.pendingTaskCommands?.get(expectedCommandId) === task
+            && owner.deviceId === safeString(device?.deviceId, 160)
+            && owner.sessionId === safeString(device?.sessionId, 160)
+            && owner.commandId === expectedCommandId
+            && owner.taskId === safeString(task?.taskId, 128)
+            && owner.operation === safeString(task?.operation, 80)
+            && owner.batchId === safeString(task?.batchId, 128);
+    }
+
+    function taskResultMatchesOwner(device, task, commandId, result, message, channel) {
+        if (channel !== 'control' || !isPendingAgentTaskOwner(device, task, commandId)) {
+            return false;
+        }
+        const owner = task.owner;
+        const resultTaskId = safeString(message?.taskId || result?.taskId, 128);
+        const resultOperation = safeString(message?.operation || result?.operation, 80);
+        const resultDeviceId = safeString(message?.deviceId || result?.deviceId, 160);
+        const resultSessionId = safeString(message?.sessionId || result?.sessionId, 160);
+        return (!resultTaskId || resultTaskId === owner.taskId)
+            && (!resultOperation || resultOperation === owner.operation)
+            && (!resultDeviceId || resultDeviceId === owner.deviceId)
+            && (!resultSessionId || resultSessionId === owner.sessionId);
+    }
+
+    function canQueueAgentTask(device) {
+        if (!(device?.pendingTaskCommands instanceof Map)
+            || !(device?.pendingTaskTimers instanceof Map)) {
+            return false;
+        }
+        // Each pending task has one exact timer. Any mismatch is unsafe state,
+        // so reject new work instead of making the retained owner unbounded.
+        if (device.pendingTaskCommands.size !== device.pendingTaskTimers.size) {
+            return false;
+        }
+        return device.pendingTaskCommands.size < MAX_PENDING_AGENT_TASKS_PER_DEVICE;
+    }
 
     function trimTaskBatches() {
         const ordered = [...taskBatches.values()]
@@ -5212,17 +5607,19 @@ export function createRemoteHub(options = {}) {
         const instruction = safeText(options.instruction, MAX_AGENT_TASK_CHARS);
         const operation = normalizeAgentOperation(options.operation);
         const targetQuery = safeText(options.targetQuery, 160);
-        const batchId = safeString(options.batchId, 128) || crypto.randomUUID();
+        const batchId = crypto.randomUUID();
         const title = safeString(options.title, 120)
             || safeString(instruction.split(/\r?\n/)[0], 120)
             || 'Remote task batch';
-        const batch = {
+        const batch = {
             batchId,
             title,
             instructionPreview: safeText(instruction, 320),
             operation,
             targetQuery,
-            approvalLevel: normalizeApprovalLevel(options.approvalLevel),
+            approvalLevel: normalizeApprovalLevel(options.approvalLevel),
+            retryToolArguments: safeRetryToolArguments(operation, options.toolArguments),
+            retryPermissionMode: normalizeAgentPermissionMode(operation, options.permissionMode),
             status: targets.length > 0 ? 'running' : 'failed',
             requestedAt: now,
             updatedAt: now,
@@ -5249,7 +5646,7 @@ export function createRemoteHub(options = {}) {
             }))
         };
 
-        taskBatches.set(batchId, batch);
+        taskBatches.set(batchId, markOwnedTaskBatch(batch));
         trimTaskBatches();
         return batch;
     }
@@ -5394,11 +5791,11 @@ export function createRemoteHub(options = {}) {
             return null;
         }
 
-        const task = device.pendingTaskCommands.get(key);
-        if (!task) {
-            clearTaskTimeout(device, key);
-            return null;
-        }
+        const task = device.pendingTaskCommands.get(key);
+        if (!task || !isPendingAgentTaskOwner(device, task, key)) {
+            clearTaskTimeout(device, key);
+            return null;
+        }
 
         const now = new Date().toISOString();
         clearTaskTimeout(device, key);
@@ -5915,62 +6312,66 @@ export function createRemoteHub(options = {}) {
             return;
         }
 
-        clearTaskTimeout(device, commandId);
-        const timer = setTimeout(() => {
-            failPendingTask(device, commandId, 'task-timeout');
-        }, taskTimeoutMs);
+        clearTaskTimeout(device, commandId);
+        const timer = setTimeout(() => {
+            if (isPendingAgentTaskOwner(device, task, commandId)) {
+                failPendingTask(device, commandId, 'task-timeout');
+            }
+        }, taskTimeoutMs);
         timer.unref?.();
         device.pendingTaskTimers.set(commandId, timer);
     }
 
-    function summarizeTaskResult(result) {
-        if (result && typeof result === 'object') {
-            return safeText(
-                result.summary
-                    || result.message
-                    || result.output
-                    || result.result
-                    || JSON.stringify(result),
-                MAX_AGENT_TASK_RESULT_CHARS);
-        }
-
-        return safeText(result ?? '', MAX_AGENT_TASK_RESULT_CHARS);
+    function summarizeTaskResult(result, diagnostic = false) {
+        let summary;
+        if (result && typeof result === 'object') {
+            try {
+                summary = result.summary
+                    || result.message
+                    || result.output
+                    || result.result
+                    || JSON.stringify(result);
+            } catch {
+                summary = '';
+            }
+        } else {
+            summary = result ?? '';
+        }
+        return diagnostic
+            ? safeDiagnosticText(summary, MAX_AGENT_TASK_RESULT_CHARS)
+            : safeText(summary, MAX_AGENT_TASK_RESULT_CHARS);
     }
 
-    function applyTaskResult(device, commandId, result, error) {
-        if (!device || !commandId) {
-            return null;
-        }
-
-        const resultTaskId = result && typeof result === 'object'
-            ? safeString(result.taskId, 128)
-            : '';
-        const task = resultTaskId
-            ? device.recentTasks.find(item => item.taskId === resultTaskId)
-            : device.pendingTaskCommands.get(commandId);
-        if (!task) {
-            return null;
-        }
-
-        if (device.pendingTaskCommands.get(commandId) !== task) {
-            return null;
-        }
+    function applyTaskResult(device, commandId, result, error, message = {}, channel = 'control') {
+        if (!device || !commandId) {
+            return null;
+        }
+        const task = device.pendingTaskCommands.get(commandId);
+        if (!task || !taskResultMatchesOwner(device, task, commandId, result, message, channel)) {
+            return null;
+        }
 
         const now = device.lastSeenAt || new Date().toISOString();
-        const resultFailed = Boolean(error)
-            || result?.ok === false
-            || safeString(result?.status, 40) === 'failed';
-        const status = resultFailed ? 'failed' : safeString(result?.status, 40) || 'completed';
-        const resultError = safeString(error, 500)
-            || safeString(result?.error, 500)
-            || (resultFailed ? safeString(result?.summary, 500) || 'agent-task-failed' : '');
+        const resultFailed = Boolean(error)
+            || result?.ok === false
+            || safeString(result?.status, 40) === 'failed';
+        const status = resultFailed ? 'failed' : safeString(result?.status, 40) || 'completed';
+        const diagnostic = DIAGNOSTIC_AGENT_OPERATIONS.has(task.operation);
+        const safeResultError = value => diagnostic
+            ? safeDiagnosticText(value, 500)
+            : safeString(value, 500);
+        const resultError = safeResultError(error)
+            || safeResultError(result?.error)
+            || (resultFailed ? safeResultError(result?.summary) || 'agent-task-failed' : '');
         clearTaskTimeout(device, commandId);
         task.status = status;
         task.updatedAt = now;
         task.completedAt = safeString(result?.completedAt, 80) || now;
         task.error = resultError;
-        task.resultSummary = resultError || summarizeTaskResult(result);
-        task.resultData = safeTaskData(result?.data);
+        task.resultSummary = resultError || summarizeTaskResult(result, diagnostic);
+        task.resultData = diagnostic
+            ? safeDiagnosticTaskData(result?.data)
+            : safeTaskData(result?.data);
         task.resultKind = safeString(result?.kind || result?.mode || 'agent-task', 80);
         device.latestTask = task;
         device.pendingTaskCommands.delete(commandId);
@@ -7689,7 +8090,7 @@ export function createRemoteHub(options = {}) {
         };
     }
 
-    function writeFrameTransportProofResponse(socket, result) {
+    function writeFrameTransportProofResponse(socket, result) {
         const proof = result?.proof;
         if (!proof?.proofId) return;
         const accepted = result.proofAccepted === true;
@@ -7705,24 +8106,98 @@ export function createRemoteHub(options = {}) {
             streamPurpose: proof.streamPurpose,
             monitorIndex: proof.monitorIndex,
             ...(accepted ? {} : { error: safeString(result.error || 'frame-proof-rejected', 160) })
-        });
-    }
-
-    function handleAgentBinaryFrame(socket, state, header, framePayload) {
+        });
+    }
+
+    function isCurrentAgentSocketOwner(socket, state, device) {
+        if (!device?.connected
+            || devices.get(device.deviceId) !== device
+            // Both values are the same Hub-created immutable session owner
+            // captured during hello. Exact comparison preserves the boundary
+            // without running general-purpose text cleanup on every frame.
+            || state?.sessionId !== device.sessionId) {
+            return false;
+        }
+        if (state.inputOnly) return device.inputSocket === socket;
+        if (state.frameOnly) return device.frameSocket === socket;
+        if (state.audioOnly) return device.audioSocket === socket;
+        if (state.fileOnly) return device.fileSocket === socket;
+        return device.socket === socket;
+    }
+
+    function getAgentMessageChannel(state) {
+        if (state?.inputOnly) return 'input';
+        if (state?.frameOnly) return 'frame';
+        if (state?.audioOnly) return 'audio';
+        if (state?.fileOnly) return 'file';
+        return 'control';
+    }
+
+    function failCloseMediaSideChannel(socket, state, reason, error = 'media-side-channel-message-not-supported') {
+        const device = state?.device;
+        if (device) {
+            emitRemoteEvent('RemoteAgentMessageIgnored', device, {
+                channel: getAgentMessageChannel(state),
+                reason
+            });
+        }
+        // Drain only this side-channel ingress. The main control owner and all
+        // other side-channel owners remain untouched.
+        closeAgentBinaryIngress(state, reason);
+        writeJsonLineAndClose(socket, { type: 'error', error });
+    }
+
+    function isAllowedMediaBinaryKind(state, frameKind) {
+        if (state?.frameOnly === true) {
+            return frameKind === 'thumbnail' || frameKind === 'stream' || frameKind === 'live';
+        }
+        if (state?.audioOnly === true) {
+            return frameKind === 'audio' || frameKind === 'audio-status';
+        }
+        return true;
+    }
+
+    function getBinaryFrameMaxBytes(frameKind) {
+        if (frameKind === 'thumbnail') return MAX_THUMBNAIL_BINARY_BYTES;
+        if (frameKind === 'audio' || frameKind === 'audio-status') return MAX_AUDIO_BINARY_BYTES;
+        return MAX_STREAM_BINARY_BYTES;
+    }
+
+    function handleAgentBinaryFrame(socket, state, header, framePayload) {
         if (!state.authenticated || !state.device) {
             writeJsonLine(socket, { type: 'error', error: 'hello-required' });
             socket.destroy();
             return;
         }
-
-        const device = state.device;
-        if (state.inputOnly || state.fileOnly) {
-            writeJsonLine(socket, { type: 'error', error: 'input-channel-binary-not-supported' });
-            socket.destroy();
-            return;
-        }
-
-        device.counters.messagesReceived += 1;
+
+        const device = state.device;
+        if (!isCurrentAgentSocketOwner(socket, state, device)) {
+            closeAgentBinaryIngress(state, 'stale-agent-socket-owner');
+            socket.destroy();
+            return;
+        }
+        if (state.inputOnly || state.fileOnly) {
+            writeJsonLine(socket, { type: 'error', error: 'input-channel-binary-not-supported' });
+            socket.destroy();
+            return;
+        }
+
+        const hasDeclaredFrameKind = header.frameKind !== undefined
+            && header.frameKind !== null
+            && header.frameKind !== '';
+        const declaredFrameKind = hasDeclaredFrameKind
+            ? normalizeMediaBinaryKind(header.frameKind)
+            : '';
+        const frameKind = hasDeclaredFrameKind
+            ? declaredFrameKind
+            : normalizeMediaBinaryKind(header.kind || header.frameType || '');
+        if ((state.frameOnly || state.audioOnly)
+            && (!frameKind || !isAllowedMediaBinaryKind(state, frameKind))) {
+            failCloseMediaSideChannel(socket, state, 'media-side-channel-binary-kind-not-supported');
+            return;
+        }
+
+        device.counters.messagesReceived += 1;
         device.lastSeenAt = new Date().toISOString();
         if (state.frameOnly) {
             device.frameLastSeenAt = device.lastSeenAt;
@@ -7731,8 +8206,7 @@ export function createRemoteHub(options = {}) {
             device.audioLastSeenAt = device.lastSeenAt;
         }
 
-        const frameKind = safeString(header.frameKind || header.kind || header.frameType || '', 40).toLowerCase();
-        const binaryTransport = socket.__liveDeskRelayControl === true
+        const binaryTransport = socket.__liveDeskRelayControl === true
             ? 'relay-binary'
             : state.binaryTransport === 'ws-binary'
                 ? 'ws-binary'
@@ -7959,9 +8433,12 @@ export function createRemoteHub(options = {}) {
         return state.binaryIngress.enqueue(header, payload);
     }
 
-    function handleAgentMessage(socket, state, message) {
-        if (!message || typeof message !== 'object') {
-            return;
+    function handleAgentMessage(socket, state, message) {
+        if (!message || typeof message !== 'object') {
+            if (state?.authenticated && (state.frameOnly || state.audioOnly)) {
+                failCloseMediaSideChannel(socket, state, 'media-side-channel-json-value-not-supported', 'invalid-json');
+            }
+            return;
         }
 
         if (!state.authenticated) {
@@ -8022,9 +8499,10 @@ export function createRemoteHub(options = {}) {
                     return;
                 }
 
-                state.authenticated = true;
-                state.device = device;
-                state.inputOnly = true;
+                state.authenticated = true;
+                state.device = device;
+                state.sessionId = device.sessionId;
+                state.inputOnly = true;
                 return;
             }
             if (channel === 'frame') {
@@ -8038,9 +8516,10 @@ export function createRemoteHub(options = {}) {
                     return;
                 }
 
-                state.authenticated = true;
-                state.device = device;
-                state.frameOnly = true;
+                state.authenticated = true;
+                state.device = device;
+                state.sessionId = device.sessionId;
+                state.frameOnly = true;
                 return;
             }
             if (channel === 'audio') {
@@ -8049,9 +8528,10 @@ export function createRemoteHub(options = {}) {
                     return;
                 }
 
-                state.authenticated = true;
-                state.device = device;
-                state.audioOnly = true;
+                state.authenticated = true;
+                state.device = device;
+                state.sessionId = device.sessionId;
+                state.audioOnly = true;
                 return;
             }
             if (channel === 'file') {
@@ -8060,9 +8540,10 @@ export function createRemoteHub(options = {}) {
                     return;
                 }
 
-                state.authenticated = true;
-                state.device = device;
-                state.fileOnly = true;
+                state.authenticated = true;
+                state.device = device;
+                state.sessionId = device.sessionId;
+                state.fileOnly = true;
                 return;
             }
 
@@ -8071,21 +8552,23 @@ export function createRemoteHub(options = {}) {
                 return;
             }
 
-            state.authenticated = true;
-            state.device = device;
-            return;
-        }
-
-        const device = state.device;
-        if (!device) {
-            socket.destroy();
-            return;
+            state.authenticated = true;
+            state.device = device;
+            state.sessionId = device.sessionId;
+            return;
         }
 
+        const device = state.device;
+        if (!device) {
+            socket.destroy();
+            return;
+        }
+        if (!isCurrentAgentSocketOwner(socket, state, device)) {
+            socket.destroy();
+            return;
+        }
+
         if (state.inputOnly) {
-            if (device.inputSocket !== socket) {
-                return;
-            }
             device.inputLastSeenAt = new Date().toISOString();
             if (message.type === 'input.applied' || message.type === 'input.error') {
                 acknowledgePendingDedicatedInput(device, message);
@@ -8095,21 +8578,50 @@ export function createRemoteHub(options = {}) {
                 }, 'input');
             }
             return;
-        }
-        if (state.frameOnly) {
-            device.frameLastSeenAt = new Date().toISOString();
-            return;
-        }
-        if (state.audioOnly) {
-            device.audioLastSeenAt = new Date().toISOString();
-            return;
-        }
+        }
+        if (state.frameOnly) {
+            switch (message.type) {
+                case 'thumbnail.frame':
+                case 'stream.open':
+                case 'stream.frame': {
+                    const receivedAt = new Date().toISOString();
+                    device.counters.messagesReceived += 1;
+                    device.frameLastSeenAt = receivedAt;
+                    device.lastSeenAt = receivedAt;
+                    if (message.type === 'thumbnail.frame') {
+                        applyThumbnailFrame(device, message, message.data, 'json-base64-frame-channel');
+                    } else if (message.type === 'stream.open') {
+                        applyLiveStreamOpen(device, message, 'json-frame-channel');
+                    } else {
+                        applyLiveFrame(device, message, message.data, 'json-base64-frame-channel');
+                    }
+                    break;
+                }
+                default:
+                    failCloseMediaSideChannel(socket, state, 'frame-channel-message-not-supported', 'frame-channel-message-not-supported');
+                    break;
+            }
+            return;
+        }
+        if (state.audioOnly) {
+            if (message.type !== 'audio.frame') {
+                failCloseMediaSideChannel(socket, state, 'audio-channel-message-not-supported', 'audio-channel-message-not-supported');
+                return;
+            }
+            const receivedAt = new Date().toISOString();
+            device.counters.messagesReceived += 1;
+            device.audioLastSeenAt = receivedAt;
+            device.lastSeenAt = receivedAt;
+            applyAudioFrame(device, message, message.data, 'json-base64-audio-channel');
+            return;
+        }
         if (state.fileOnly) {
             device.fileLastSeenAt = new Date().toISOString();
         }
 
-        device.counters.messagesReceived += 1;
-        device.lastSeenAt = new Date().toISOString();
+        device.counters.messagesReceived += 1;
+        device.lastSeenAt = new Date().toISOString();
+        const channel = getAgentMessageChannel(state);
 
         switch (message.type) {
             case 'heartbeat':
@@ -8137,12 +8649,14 @@ export function createRemoteHub(options = {}) {
                         message.error || (message.type === 'command.error' ? 'command-failed' : ''),
                         500);
                     const result = message.result ?? null;
-                    settlePendingCommandResult(device, message);
-                    handleInputFallbackCommandResult(device, message);
-                    if (error || result?.ok === false || result?.status === 'failed') {
-                        failPendingLiveStream(device, commandId, error || result?.error || 'stream-start-failed');
-                    }
-                    const task = applyTaskResult(device, commandId, result, error);
+                    settlePendingCommandResult(device, message, channel);
+                    if (channel === 'control') {
+                        handleInputFallbackCommandResult(device, message);
+                        if (error || result?.ok === false || result?.status === 'failed') {
+                            failPendingLiveStream(device, commandId, error || result?.error || 'stream-start-failed');
+                        }
+                    }
+                    const task = applyTaskResult(device, commandId, result, error, message, channel);
                     if (task) {
                         emitRemoteEvent('RemoteTaskResult', device, {
                             commandId,
@@ -8158,8 +8672,16 @@ export function createRemoteHub(options = {}) {
                     error: safeString(message.error, 500)
                 });
                 break;
-            case 'client.update.verified': {
-                const receivedAt = new Date().toISOString();
+            case 'client.update.verified': {
+                if (channel !== 'control') {
+                    emitRemoteEvent('RemoteAgentMessageIgnored', device, {
+                        channel,
+                        messageType: 'client.update.verified',
+                        reason: 'client-update-proof-control-channel-required'
+                    });
+                    break;
+                }
+                const receivedAt = new Date().toISOString();
                 const proof = normalizeClientUpdateVerifiedProof(device, message, receivedAt);
                 if (!proof) {
                     logWarn(
@@ -8205,10 +8727,11 @@ export function createRemoteHub(options = {}) {
         socket.setNoDelay(true);
         socket.setKeepAlive(true, heartbeatMs);
 
-        const state = {
-            authenticated: false,
-            device: null,
-            binaryTransport: 'ws-binary',
+        const state = {
+            authenticated: false,
+            device: null,
+            sessionId: '',
+            binaryTransport: 'ws-binary',
             inputOnly: false,
             frameOnly: false,
             audioOnly: false,
@@ -8228,33 +8751,56 @@ export function createRemoteHub(options = {}) {
             }
         }, 10000);
 
-        socket.onTextMessage = text => {
-            try {
-                handleAgentMessage(socket, state, parseJsonLine(String(text || '')));
-            } catch (err) {
-                writeJsonLine(socket, { type: 'error', error: 'invalid-json' });
-                logWarn('remote', `invalid websocket agent message: ${err?.message || err}`);
-            }
+        socket.onTextMessage = text => {
+            try {
+                handleAgentMessage(socket, state, parseJsonLine(String(text || '')));
+            } catch (err) {
+                if (state.authenticated && (state.frameOnly || state.audioOnly)) {
+                    failCloseMediaSideChannel(socket, state, 'media-side-channel-malformed-json', 'invalid-json');
+                    return;
+                }
+                writeJsonLine(socket, { type: 'error', error: 'invalid-json' });
+                logWarn('remote', `invalid websocket agent message: ${err?.message || err}`);
+            }
         };
 
         socket.onBinaryMessage = payload => {
             try {
                 const packet = parseRemoteHubWebSocketBinaryFrame(payload);
-                if (!packet?.header || !Buffer.isBuffer(packet.payload)) {
-                    writeJsonLine(socket, { type: 'error', error: 'invalid-websocket-binary-frame' });
-                    return;
-                }
-
-                const frameKind = safeString(packet.header.frameKind || packet.header.kind || packet.header.frameType, 40).toLowerCase();
-                const maxBytes = frameKind === 'thumbnail'
-                    ? MAX_THUMBNAIL_BINARY_BYTES
-                    : MAX_STREAM_BINARY_BYTES;
-                const byteLength = Number(packet.header.byteLength ?? packet.header.payloadBytes ?? packet.payload.length);
-                if (!Number.isFinite(byteLength)
-                    || byteLength < 1
-                    || byteLength > maxBytes
-                    || byteLength !== packet.payload.length) {
-                    writeJsonLine(socket, { type: 'error', error: 'invalid-binary-frame' });
+                if (!packet?.header || !Buffer.isBuffer(packet.payload)) {
+                    if (state.authenticated && (state.frameOnly || state.audioOnly)) {
+                        failCloseMediaSideChannel(socket, state, 'media-side-channel-malformed-binary', 'invalid-websocket-binary-frame');
+                        return;
+                    }
+                    writeJsonLine(socket, { type: 'error', error: 'invalid-websocket-binary-frame' });
+                    return;
+                }
+
+                const hasDeclaredFrameKind = packet.header.frameKind !== undefined
+                    && packet.header.frameKind !== null
+                    && packet.header.frameKind !== '';
+                const declaredFrameKind = hasDeclaredFrameKind
+                    ? normalizeMediaBinaryKind(packet.header.frameKind)
+                    : '';
+                const frameKind = hasDeclaredFrameKind
+                    ? declaredFrameKind
+                    : normalizeMediaBinaryKind(packet.header.kind || packet.header.frameType);
+                if ((state.frameOnly || state.audioOnly)
+                    && (!frameKind || !isAllowedMediaBinaryKind(state, frameKind))) {
+                    failCloseMediaSideChannel(socket, state, 'media-side-channel-binary-kind-not-supported');
+                    return;
+                }
+                const maxBytes = getBinaryFrameMaxBytes(frameKind);
+                const byteLength = Number(packet.header.byteLength ?? packet.header.payloadBytes ?? packet.payload.length);
+                if (!Number.isFinite(byteLength)
+                    || byteLength < 1
+                    || byteLength > maxBytes
+                    || byteLength !== packet.payload.length) {
+                    if (state.authenticated && (state.frameOnly || state.audioOnly)) {
+                        failCloseMediaSideChannel(socket, state, 'media-side-channel-invalid-binary-length', 'invalid-binary-frame');
+                        return;
+                    }
+                    writeJsonLine(socket, { type: 'error', error: 'invalid-binary-frame' });
                     logWarn('remote', 'invalid websocket binary frame from agent.');
                     return;
                 }
@@ -8382,10 +8928,11 @@ export function createRemoteHub(options = {}) {
         socket.setNoDelay(true);
         socket.setKeepAlive(true, heartbeatMs);
 
-        const state = {
-            authenticated: false,
-            device: null,
-            binaryTransport: 'binary',
+        const state = {
+            authenticated: false,
+            device: null,
+            sessionId: '',
+            binaryTransport: 'binary',
             inputOnly: false,
             frameOnly: false,
             audioOnly: false,
@@ -8451,24 +8998,14 @@ export function createRemoteHub(options = {}) {
                     }
 
                     if (startsWithTcpBinaryFrameMagic(state.buffer)) {
-                        const packet = parseTcpBinaryFramePacket(state.buffer);
-                        if (packet?.incomplete) {
-                            return;
-                        }
-                        if (!packet || packet.invalid) {
-                            const syncIndex = findTcpFrameOnlySyncIndex(state.buffer, 1);
-                            if (syncIndex > 0) {
-                                state.buffer.discard(syncIndex);
-                                state.lineScanOffset = 0;
-                                continue;
-                            }
-
-                            const syncTail = keepTcpFrameOnlySyncTail(state.buffer);
-                            state.buffer.clear();
-                            state.buffer.append(syncTail);
-                            state.lineScanOffset = 0;
-                            return;
-                        }
+                        const packet = parseTcpBinaryFramePacket(state.buffer);
+                        if (packet?.incomplete) {
+                            return;
+                        }
+                        if (!packet || packet.invalid) {
+                            failCloseMediaSideChannel(socket, state, 'media-side-channel-malformed-binary', 'invalid-binary-frame');
+                            return;
+                        }
 
                         state.buffer.discard(packet.packetLength);
                         state.lineScanOffset = 0;
@@ -8476,20 +9013,10 @@ export function createRemoteHub(options = {}) {
                         continue;
                     }
 
-                    if (!isJsonObjectStartByte(state.buffer.byteAt(0))) {
-                        const syncIndex = findTcpFrameOnlySyncIndex(state.buffer, 1);
-                        if (syncIndex > 0) {
-                            state.buffer.discard(syncIndex);
-                            state.lineScanOffset = 0;
-                            continue;
-                        }
-
-                        const syncTail = keepTcpFrameOnlySyncTail(state.buffer);
-                        state.buffer.clear();
-                        state.buffer.append(syncTail);
-                        state.lineScanOffset = 0;
-                        return;
-                    }
+                    if (!isJsonObjectStartByte(state.buffer.byteAt(0))) {
+                        failCloseMediaSideChannel(socket, state, 'media-side-channel-malformed-binary', 'invalid-binary-frame');
+                        return;
+                    }
                 }
 
                 const newlineIndex = state.buffer.indexOfByte(0x0a, state.lineScanOffset);
@@ -8511,18 +9038,33 @@ export function createRemoteHub(options = {}) {
                     return;
                 }
 
-                try {
-                    const message = parseJsonLine(lineBuffer.toString('utf8'));
-                    if (message?.type === 'frame.binary') {
-                        const frameKind = safeString(message.frameKind || message.kind || message.frameType, 40).toLowerCase();
-                        const maxBytes = frameKind === 'thumbnail'
-                            ? MAX_THUMBNAIL_BINARY_BYTES
-                            : MAX_STREAM_BINARY_BYTES;
-                        const byteLength = Number(message.byteLength ?? message.payloadBytes ?? message.dataLength);
-                        if (!Number.isFinite(byteLength) || byteLength < 1 || byteLength > maxBytes) {
-                            writeJsonLine(socket, { type: 'error', error: 'invalid-binary-frame' });
-                            logWarn('remote', 'invalid binary frame header from agent.');
-                            continue;
+                try {
+                    const message = parseJsonLine(lineBuffer.toString('utf8'));
+                    if (message?.type === 'frame.binary') {
+                        const hasDeclaredFrameKind = message.frameKind !== undefined
+                            && message.frameKind !== null
+                            && message.frameKind !== '';
+                        const declaredFrameKind = hasDeclaredFrameKind
+                            ? normalizeMediaBinaryKind(message.frameKind)
+                            : '';
+                        const frameKind = hasDeclaredFrameKind
+                            ? declaredFrameKind
+                            : normalizeMediaBinaryKind(message.kind || message.frameType);
+                        if ((state.frameOnly || state.audioOnly)
+                            && (!frameKind || !isAllowedMediaBinaryKind(state, frameKind))) {
+                            failCloseMediaSideChannel(socket, state, 'media-side-channel-binary-kind-not-supported');
+                            return;
+                        }
+                        const maxBytes = getBinaryFrameMaxBytes(frameKind);
+                        const byteLength = Number(message.byteLength ?? message.payloadBytes ?? message.dataLength);
+                        if (!Number.isFinite(byteLength) || byteLength < 1 || byteLength > maxBytes) {
+                            if (state.authenticated && (state.frameOnly || state.audioOnly)) {
+                                failCloseMediaSideChannel(socket, state, 'media-side-channel-invalid-binary-length', 'invalid-binary-frame');
+                                return;
+                            }
+                            writeJsonLine(socket, { type: 'error', error: 'invalid-binary-frame' });
+                            logWarn('remote', 'invalid binary frame header from agent.');
+                            continue;
                         }
 
                         state.pendingBinaryFrame = {
@@ -8532,11 +9074,12 @@ export function createRemoteHub(options = {}) {
                         continue;
                     }
 
-                    handleAgentMessage(socket, state, message);
-                } catch (err) {
-                    if (state.authenticated && (state.frameOnly || state.audioOnly)) {
-                        continue;
-                    }
+                    handleAgentMessage(socket, state, message);
+                } catch (err) {
+                    if (state.authenticated && (state.frameOnly || state.audioOnly)) {
+                        failCloseMediaSideChannel(socket, state, 'media-side-channel-malformed-json', 'invalid-json');
+                        return;
+                    }
                     writeJsonLine(socket, { type: 'error', error: 'invalid-json' });
                     logWarn('remote', `invalid agent message: ${err?.message || err}`);
                 }
@@ -8650,20 +9193,36 @@ export function createRemoteHub(options = {}) {
         });
     }
 
-    async function start() {
-        if (!enabled || started) {
-            return getStatus({ includeSecrets: false });
-        }
-
-        try {
-            await udpTransport?.start?.();
-            await listenOnPort(requestedPort);
-            try {
-                await relayControl?.start?.();
-            } catch {
-                logWarn('relay', 'Encrypted relay control could not start; direct TCP remains available.');
-            }
-            scheduleDeviceConnectionSweep();
+    async function start() {
+        if (!enabled || started) {
+            return getStatus({ includeSecrets: false });
+        }
+
+        try {
+            closing = false;
+            await listenOnPort(requestedPort);
+            // Direct TCP is the authoritative Client control path. UDP is an
+            // optional frame optimization, so a temporary socket/DNS failure
+            // must not keep the Hub offline after its Direct listener is ready.
+            // UDP is optional and may be delayed by a sleeping adapter or a
+            // transient bind failure. Its exact promise remains owned for
+            // retry and shutdown, but it must never hold the Hub HTTP/PWA
+            // startup path behind the already-listening Direct TCP socket.
+            void startOptionalUdpTransport('startup');
+            // Product relay status is permanently disabled. Do not even call
+            // its dormant start owner; only explicitly injected retired-protocol
+            // tests can expose enabled=true.
+            if (relayControl?.getStatus?.().enabled === true) {
+                try {
+                    await relayControl?.start?.();
+                } catch {
+                    logWarn('relay', 'Encrypted relay control could not start; direct TCP remains available.');
+                }
+            }
+            if (closing || !started) {
+                return getStatus({ includeSecrets: false });
+            }
+            scheduleDeviceConnectionSweep();
         } catch (error) {
             if (error?.code === 'EADDRINUSE') {
                 const conflict = new Error(
@@ -8680,8 +9239,14 @@ export function createRemoteHub(options = {}) {
         return getStatus({ includeSecrets: false });
     }
 
-    async function close() {
-        if (deviceConnectionSweepTimer) {
+    async function close() {
+        closing = true;
+        if (udpStartRetryTimer) {
+            clearTimeout(udpStartRetryTimer);
+            udpStartRetryTimer = null;
+        }
+        const pendingUdpStart = udpStartPromise;
+        if (deviceConnectionSweepTimer) {
             clearTimeout(deviceConnectionSweepTimer);
             deviceConnectionSweepTimer = null;
         }
@@ -8693,9 +9258,12 @@ export function createRemoteHub(options = {}) {
             abortTransportDiagnosticsForDevice(device, 'hub-shutdown');
             failAllPendingTasks(device, 'hub-shutdown');
             failAllPendingInputFallbacks(device, 'hub-shutdown');
-            failPendingCommandResultWaiters(device, 'hub-shutdown');
-            closeInputSocket(device, 'hub-shutdown');
-            if (device.socket && !device.socket.destroyed) {
+            failPendingCommandResultWaiters(device, 'hub-shutdown');
+            closeInputSocket(device, 'hub-shutdown');
+            closeFrameSocket(device, 'hub-shutdown');
+            closeAudioSocket(device, 'hub-shutdown');
+            closeFileSocket(device, 'hub-shutdown');
+            if (device.socket && !device.socket.destroyed) {
                 writeJsonLine(device.socket, { type: 'disconnect', reason: 'hub-shutdown' });
                 device.socket.destroy();
             }
@@ -8706,10 +9274,13 @@ export function createRemoteHub(options = {}) {
                 socket.destroy();
             }
         }
-
-        sockets.clear();
-        await relayControl?.close?.();
-        await udpTransport?.close?.();
+
+        sockets.clear();
+        await relayControl?.close?.();
+        if (pendingUdpStart) {
+            await pendingUdpStart;
+        }
+        await udpTransport?.close?.();
         if (!server) {
             started = false;
             return;
@@ -8843,7 +9414,7 @@ export function createRemoteHub(options = {}) {
                         : '';
         const denied = policyError(device, requiredPermission, commandName);
         if (denied) return { ok: false, error: denied };
-        if (device?.synthetic === true && device.connected) {
+        if (device?.synthetic === true && device.connected) {
             const commandId = safeString(command?.commandId, 128) || crypto.randomUUID();
             device.counters.commandsSent += 1;
             device.lastSeenAt = new Date().toISOString();
@@ -8888,12 +9459,17 @@ export function createRemoteHub(options = {}) {
             && !device.fileSocket.destroyed
             ? device.fileSocket
             : null;
-        try {
-            writeJsonLine(dedicatedFileSocket || device.socket, payload);
-        } catch {
-            retireStaleDeviceConnection(device, 'command-channel-write-failed');
-            return { ok: false, error: 'device-not-connected' };
-        }
+        let sent = false;
+        try {
+            sent = writeJsonLine(dedicatedFileSocket || device.socket, payload);
+        } catch {
+            retireStaleDeviceConnection(device, 'command-channel-write-failed');
+            return { ok: false, error: 'device-not-connected' };
+        }
+        if (!sent) {
+            retireStaleDeviceConnection(device, 'command-channel-write-failed');
+            return { ok: false, error: 'device-not-connected' };
+        }
         device.counters.commandsSent += 1;
         emitRemoteEvent('RemoteCommandQueued', device, {
             commandId,
@@ -9734,14 +10310,23 @@ export function createRemoteHub(options = {}) {
         }
         const device = devices.get(String(deviceId || ''));
         const requestedOperation = safeString(options.operation, 80);
-        const operation = normalizeAgentOperation(requestedOperation);
-        if (requestedOperation && !operation) {
-            return { ok: false, error: 'unsupported-agent-operation' };
-        }
-        if (!device) {
-            return { ok: false, error: 'device-not-found' };
-        }
-        const denied = policyError(device, 'allowAgent');
+        const operation = normalizeAgentOperation(requestedOperation);
+        if (requestedOperation && !operation) {
+            return { ok: false, error: 'unsupported-agent-operation' };
+        }
+        const normalizedToolArguments = normalizeAgentToolArguments(operation, options.toolArguments);
+        if (!normalizedToolArguments.ok) {
+            return { ok: false, error: normalizedToolArguments.error };
+        }
+        const toolArguments = normalizedToolArguments.value;
+        const permissionMode = normalizeAgentPermissionMode(operation, options.permissionMode);
+        if (!device) {
+            return { ok: false, error: 'device-not-found' };
+        }
+        if (operation && !deviceSupportsAgentOperation(device, operation)) {
+            return { ok: false, error: 'agent-operation-not-advertised' };
+        }
+        const denied = policyError(device, 'allowAgent');
         if (denied) return { ok: false, error: denied };
 
         if (device?.synthetic === true && device.connected) {
@@ -9752,21 +10337,21 @@ export function createRemoteHub(options = {}) {
 
             const now = new Date().toISOString();
             const approvalLevel = normalizeApprovalLevel(options.approvalLevel);
-            const commandId = safeString(options.commandId, 128) || crypto.randomUUID();
-            const taskId = safeString(options.taskId, 128) || crypto.randomUUID();
+            const commandId = crypto.randomUUID();
+            const taskId = crypto.randomUUID();
+            const batch = getOwnedTaskBatch(options);
             const title = safeString(options.title, 120)
                 || safeString(instruction.split(/\r?\n/)[0], 120)
                 || 'Remote task';
             const task = {
-                batchId: safeString(options.batchId, 128),
+                batchId: batch?.batchId || '',
                 taskId,
                 commandId,
                 title,
-                 operation,
-                 targetQuery: safeText(options.targetQuery, 160),
-                 toolArguments: options.toolArguments && typeof options.toolArguments === 'object' ? options.toolArguments : {},
-                 permissionMode: safeString(options.permissionMode, 40) || 'ask',
-                 instructionPreview: safeText(instruction, 320),
+                operation,
+                targetQuery: safeText(options.targetQuery, 160),
+                permissionMode,
+                instructionPreview: safeText(instruction, 320),
                 status: 'completed',
                 stage: 'Completed',
                 approvalLevel,
@@ -9779,8 +10364,14 @@ export function createRemoteHub(options = {}) {
                 resultSummary: operation === 'process.list'
                     ? 'Process list collected.'
                     : `Synthetic task accepted by ${device.deviceName}.`,
-                resultData: undefined
-            };
+                resultData: undefined
+            };
+            Object.defineProperty(task, 'owner', {
+                value: createAgentTaskOwner(device, taskId, commandId, operation, task.batchId),
+                enumerable: false,
+                configurable: false,
+                writable: false
+            });
 
             device.counters.commandsSent += 1;
             device.counters.commandResultsReceived += 1;
@@ -9811,9 +10402,12 @@ export function createRemoteHub(options = {}) {
             retireStaleDeviceConnection(device, 'status-heartbeat-timeout');
             return { ok: false, error: 'device-not-connected' };
         }
-        if (!device?.socket || device.socket.destroyed || !device.connected) {
-            return { ok: false, error: 'device-not-connected' };
-        }
+        if (!device?.socket || device.socket.destroyed || !device.connected) {
+            return { ok: false, error: 'device-not-connected' };
+        }
+        if (!canQueueAgentTask(device)) {
+            return { ok: false, error: 'agent-task-capacity-reached' };
+        }
 
         const instruction = safeText(options.instruction, MAX_AGENT_TASK_CHARS);
         if (!instruction) {
@@ -9822,21 +10416,21 @@ export function createRemoteHub(options = {}) {
 
         const now = new Date().toISOString();
         const approvalLevel = normalizeApprovalLevel(options.approvalLevel);
-        const commandId = safeString(options.commandId, 128) || crypto.randomUUID();
-        const taskId = safeString(options.taskId, 128) || crypto.randomUUID();
+        const commandId = crypto.randomUUID();
+        const taskId = crypto.randomUUID();
+        const batch = getOwnedTaskBatch(options);
         const title = safeString(options.title, 120)
             || safeString(instruction.split(/\r?\n/)[0], 120)
             || 'Remote task';
         const task = {
-            batchId: safeString(options.batchId, 128),
+            batchId: batch?.batchId || '',
             taskId,
             commandId,
             title,
-             operation,
-             targetQuery: safeText(options.targetQuery, 160),
-             toolArguments: options.toolArguments && typeof options.toolArguments === 'object' ? options.toolArguments : {},
-             permissionMode: safeString(options.permissionMode, 40) || 'ask',
-             instructionPreview: safeText(instruction, 320),
+            operation,
+            targetQuery: safeText(options.targetQuery, 160),
+            permissionMode,
+            instructionPreview: safeText(instruction, 320),
             status: 'queued',
             stage: operation === 'process.list' ? 'Checking processes' : 'Queued',
             approvalLevel,
@@ -9847,8 +10441,14 @@ export function createRemoteHub(options = {}) {
             error: '',
             resultKind: '',
             resultSummary: '',
-            resultData: undefined
-        };
+            resultData: undefined
+        };
+        Object.defineProperty(task, 'owner', {
+            value: createAgentTaskOwner(device, taskId, commandId, operation, task.batchId),
+            enumerable: false,
+            configurable: false,
+            writable: false
+        });
 
         const commandName = operation || 'agent.task';
         const sent = writeJsonLine(device.socket, {
@@ -9859,11 +10459,11 @@ export function createRemoteHub(options = {}) {
                 taskId,
                 title,
                 instruction,
-                 operation,
-                 targetQuery: safeText(options.targetQuery, 160),
-                 toolArguments: options.toolArguments && typeof options.toolArguments === 'object' ? options.toolArguments : {},
-                 permissionMode: safeString(options.permissionMode, 40) || 'ask',
-                 approvalLevel,
+                operation,
+                targetQuery: safeText(options.targetQuery, 160),
+                toolArguments,
+                permissionMode,
+                approvalLevel,
                 requestedAt: now
             },
             issuedAt: now
@@ -9905,23 +10505,52 @@ export function createRemoteHub(options = {}) {
             };
         }
 
-        if (targets.length === 0) {
+        if (targets.length === 0) {
             return {
                 ok: false,
                 error: 'no-target-devices',
                 total: 0,
                 queued: 0,
                 approvalLevel: normalizeApprovalLevel(options.approvalLevel),
-                results: []
-            };
-        }
-
-        const batch = beginTaskBatch(targets, options);
-        const results = targets.map(deviceId => {
-            const result = requestAgentTask(deviceId, {
-                ...options,
-                batchId: batch.batchId
-            });
+                results: []
+            };
+        }
+
+        const requestedOperation = safeString(options.operation, 80);
+        const operation = normalizeAgentOperation(requestedOperation);
+        if (requestedOperation && !operation) {
+            return {
+                ok: false,
+                error: 'unsupported-agent-operation',
+                total: targets.length,
+                queued: 0,
+                approvalLevel: normalizeApprovalLevel(options.approvalLevel),
+                results: []
+            };
+        }
+        const normalizedToolArguments = normalizeAgentToolArguments(operation, options.toolArguments);
+        if (!normalizedToolArguments.ok) {
+            return {
+                ok: false,
+                error: normalizedToolArguments.error,
+                total: targets.length,
+                queued: 0,
+                approvalLevel: normalizeApprovalLevel(options.approvalLevel),
+                results: []
+            };
+        }
+        const normalizedOptions = {
+            ...options,
+            operation,
+            toolArguments: normalizedToolArguments.value,
+            permissionMode: normalizeAgentPermissionMode(operation, options.permissionMode)
+        };
+        const batch = beginTaskBatch(targets, normalizedOptions);
+        const results = targets.map(deviceId => {
+            const result = requestAgentTask(deviceId, {
+                ...normalizedOptions,
+                taskBatch: batch
+            });
 
             if (result.ok !== true) {
                 syncTaskBatchDispatchFailure(batch.batchId, deviceId, result.error, result);