@livedesk/hub 0.1.24 → 0.1.26

package/src/remote-hub.js

@@ -31,6 +31,17 @@ const LIVE_STREAM_MIN_FRESH_MS = 3000;
 const LIVE_STREAM_MAX_FRESH_MS = 12000;
 const DEFAULT_REMOTE_INPUT_ACK_TIMEOUT_MS = 5000;
 const DEFAULT_LIVE_CAPTURE_STOP_ACK_TIMEOUT_MS = 8000;
+const TRANSPORT_DIAGNOSTIC_MIN_TTL_MS = 15_000;
+const TRANSPORT_DIAGNOSTIC_MAX_TTL_MS = 180_000;
+const TRANSPORT_DIAGNOSTIC_COMMAND_TIMEOUT_MS = 8_000;
+const TRANSPORT_DIAGNOSTIC_RECORD_RETENTION_MS = 60_000;
+const TRANSPORT_DIAGNOSTIC_MAX_RECORDS = 32;
+const TRANSPORT_DIAGNOSTIC_PHASES = Object.freeze([
+    'direct',
+    'p2p',
+    'relay',
+    'recover-direct'
+]);
 const REMOTE_POLICY_BYPASS_COMMANDS = new Set([
     'ping',
     'stream.stop',
@@ -429,13 +440,23 @@ function isPublicIPv4(value) {
         return false;
     }
 
-    if (parts[0] === 192 && (parts[1] === 0 || parts[1] === 168)) {
-        return false;
-    }
-
-    if (parts[0] === 198 && (parts[1] === 18 || parts[1] === 19)) {
-        return false;
-    }
+    if (parts[0] === 192
+        && (parts[1] === 0
+            || parts[1] === 168
+            || (parts[1] === 88 && parts[2] === 99))) {
+        return false;
+    }
+
+    if (parts[0] === 198
+        && (parts[1] === 18
+            || parts[1] === 19
+            || (parts[1] === 51 && parts[2] === 100))) {
+        return false;
+    }
+
+    if (parts[0] === 203 && parts[1] === 0 && parts[2] === 113) {
+        return false;
+    }
 
     return true;
 }
@@ -690,21 +711,39 @@ const SUPPORTED_AGENT_OPERATIONS = new Set([
     'logs.collect'
 ]);
 
-function normalizeAgentOperation(value) {
-    const operation = safeString(value, 80).toLowerCase();
-    return SUPPORTED_AGENT_OPERATIONS.has(operation) ? operation : '';
-}
-
-function normalizeRemoteInputEvent(value = {}) {
-    const input = value && typeof value === 'object' ? value : {};
-    const type = safeString(input.type || input.Type, 48);
+function normalizeAgentOperation(value) {
+    const operation = safeString(value, 80).toLowerCase();
+    return SUPPORTED_AGENT_OPERATIONS.has(operation) ? operation : '';
+}
+
+const REMOTE_INPUT_MONITOR_KEYS = Object.freeze([
+    'monitorIndex',
+    'MonitorIndex',
+    'screenIndex',
+    'ScreenIndex',
+    'displayIndex',
+    'DisplayIndex'
+]);
+
+function readRawRemoteInputMonitorIndex(input) {
+    for (const key of REMOTE_INPUT_MONITOR_KEYS) {
+        if (Object.prototype.hasOwnProperty.call(input, key)) {
+            return input[key];
+        }
+    }
+    return undefined;
+}
+
+function normalizeRemoteInputEvent(value = {}) {
+    const input = value && typeof value === 'object' ? value : {};
+    const type = safeString(input.type || input.Type, 48);
     const normalizedX = Number(input.normalizedX ?? input.NormalizedX);
     const normalizedY = Number(input.normalizedY ?? input.NormalizedY);
     const deltaX = Number(input.deltaX ?? input.DeltaX);
     const deltaY = Number(input.deltaY ?? input.DeltaY);
     const keyCode = Number(input.keyCode ?? input.KeyCode);
     const location = Number(input.location ?? input.Location);
-    const monitorIndex = Number(input.monitorIndex ?? input.MonitorIndex ?? input.screenIndex ?? input.ScreenIndex ?? input.displayIndex ?? input.DisplayIndex);
+    const monitorIndex = parseExactLiveStreamMonitorIndex(readRawRemoteInputMonitorIndex(input));
     const inputSeq = Number(input.inputSeq ?? input.InputSeq);
     const issuedAtEpochMs = Number(input.issuedAtEpochMs ?? input.IssuedAtEpochMs);
     const hubReceivedAtEpochMs = Number(input.hubReceivedAtEpochMs ?? input.HubReceivedAtEpochMs);
@@ -720,7 +759,7 @@ function normalizeRemoteInputEvent(value = {}) {
         type,
         // A missing monitor is not equivalent to the primary display. Control
         // input must prove the exact monitor owned by its capture generation.
-        monitorIndex: Number.isFinite(monitorIndex) ? normalizeMonitorIndex(monitorIndex) : null,
+        monitorIndex,
         normalizedX: Number.isFinite(normalizedX) ? Math.max(0, Math.min(1, normalizedX)) : undefined,
         normalizedY: Number.isFinite(normalizedY) ? Math.max(0, Math.min(1, normalizedY)) : undefined,
         button: safeString(input.button || input.Button, 24),
@@ -1510,6 +1549,11 @@ class RemoteHubWebSocketAgentSocket {
 
 export function createRemoteHub(options = {}) {
     const env = options.env || process.env;
+    const transportDiagnosticCommandTimeoutMs = clampNumber(
+        options.transportDiagnosticCommandTimeoutMs,
+        25,
+        TRANSPORT_DIAGNOSTIC_COMMAND_TIMEOUT_MS,
+        TRANSPORT_DIAGNOSTIC_COMMAND_TIMEOUT_MS);
     const rejectFrameChannelForTest = isEnabledValue(env.LIVEDESK_TEST_MODE, false)
         && isEnabledValue(env.LIVEDESK_TEST_REJECT_FRAME_CHANNEL, false);
     const logEvent = options.logEvent || (() => {});
@@ -1613,7 +1657,9 @@ export function createRemoteHub(options = {}) {
     const fileSockets = new Map();
     const allSockets = new Set();
     const pendingCommandResultWaiters = new Map();
-    const duplicateDeviceLogAt = new Map();
+    const transportDiagnostics = new Map();
+    const transportDiagnosticStartingDevices = new Set();
+    const duplicateDeviceLogAt = new Map();
     let server = null;
     let started = false;
     let boundPort = requestedPort;
@@ -2248,6 +2294,700 @@ export function createRemoteHub(options = {}) {
         });
     }
 
+    function inspectAnnexBH264(payload) {
+        if (!Buffer.isBuffer(payload) || payload.length < 5) {
+            return {
+                annexB: false,
+                hasIdr: false,
+                hasSps: false,
+                hasPps: false,
+                nalOrderValid: false
+            };
+        }
+        let annexB = false;
+        let hasIdr = false;
+        let hasSps = false;
+        let hasPps = false;
+        let firstSpsAt = -1;
+        let firstPpsAfterSpsAt = -1;
+        let firstIdrAfterPpsAt = -1;
+        for (let index = 0; index + 4 < payload.length; index += 1) {
+            let headerIndex = -1;
+            if (payload[index] === 0 && payload[index + 1] === 0 && payload[index + 2] === 1) {
+                headerIndex = index + 3;
+            } else if (payload[index] === 0
+                && payload[index + 1] === 0
+                && payload[index + 2] === 0
+                && payload[index + 3] === 1) {
+                headerIndex = index + 4;
+            }
+            if (headerIndex < 0 || headerIndex >= payload.length) continue;
+            annexB = true;
+            const nalType = payload[headerIndex] & 0x1f;
+            if (nalType === 5) {
+                hasIdr = true;
+                if (firstPpsAfterSpsAt >= 0 && firstIdrAfterPpsAt < 0) {
+                    firstIdrAfterPpsAt = headerIndex;
+                }
+            }
+            if (nalType === 7) {
+                hasSps = true;
+                if (firstSpsAt < 0) firstSpsAt = headerIndex;
+            }
+            if (nalType === 8) {
+                hasPps = true;
+                if (firstSpsAt >= 0 && firstPpsAfterSpsAt < 0) {
+                    firstPpsAfterSpsAt = headerIndex;
+                }
+            }
+            index = headerIndex;
+        }
+        return {
+            annexB,
+            hasIdr,
+            hasSps,
+            hasPps,
+            nalOrderValid: firstSpsAt >= 0
+                && firstPpsAfterSpsAt > firstSpsAt
+                && firstIdrAfterPpsAt > firstPpsAfterSpsAt
+        };
+    }
+
+    function expectedTransportForDiagnosticPhase(phase) {
+        if (phase === 'p2p') return 'p2p';
+        if (phase === 'relay') return 'relay';
+        return 'direct';
+    }
+
+    function observedTransportPath(frame) {
+        const transport = safeString(frame?.transport, 32).toLowerCase();
+        if (transport === 'udp-p2p') return 'p2p';
+        if (transport === 'relay-binary') return 'relay';
+        if (transport === 'binary' || transport === 'ws-binary') return 'direct';
+        return '';
+    }
+
+    function optionalFiniteNumber(value) {
+        return value !== null && value !== undefined && value !== ''
+            && Number.isFinite(Number(value))
+            ? Number(value)
+            : null;
+    }
+
+    function transportDiagnosticIdentifierHash(value, salt) {
+        const normalized = safeString(value, 240);
+        return normalized
+            ? crypto.createHash('sha256')
+                .update(`${safeString(salt, 160)}:${normalized}`)
+                .digest('hex')
+                .slice(0, 16)
+            : '';
+    }
+
+    function currentTransportDiagnosticOwner(device) {
+        const frame = device?.latestLiveFrame;
+        if (!device?.connected
+            || !device.sessionId
+            || !frame
+            || frame.currentGenerationVerified !== true
+            || safeString(frame.mimeType, 80).toLowerCase() !== 'video/h264'
+            || !safeString(frame.streamId, 128)
+            || !safeString(frame.commandId, 128)
+            || Number(frame.captureGeneration || 0) <= 0) {
+            return null;
+        }
+        const monitorIndex = parseExactLiveStreamMonitorIndex(frame.monitorIndex);
+        const streamState = getDeviceLiveStream(device, frame.streamId);
+        if (monitorIndex === null
+            || !streamState?.active
+            || safeString(streamState.commandId, 128) !== safeString(frame.commandId, 128)
+            || Number(streamState.captureGeneration || 0) !== Number(frame.captureGeneration || 0)
+            || parseExactLiveStreamMonitorIndex(streamState.monitorIndex) !== monitorIndex) {
+            return null;
+        }
+        return {
+            deviceId: device.deviceId,
+            sessionId: device.sessionId,
+            streamId: safeString(frame.streamId, 128),
+            streamCommandId: safeString(frame.commandId, 128),
+            captureGeneration: Number(frame.captureGeneration),
+            monitorIndex
+        };
+    }
+
+    function transportDiagnosticOwnersEqual(left, right) {
+        return !!left
+            && !!right
+            && left.deviceId === right.deviceId
+            && left.sessionId === right.sessionId
+            && left.streamId === right.streamId
+            && left.streamCommandId === right.streamCommandId
+            && left.captureGeneration === right.captureGeneration
+            && left.monitorIndex === right.monitorIndex;
+    }
+
+    function transportDiagnosticOwnerMatches(record, device) {
+        const current = currentTransportDiagnosticOwner(device);
+        return transportDiagnosticOwnersEqual(current, record.owner);
+    }
+
+    function serializeTransportDiagnostic(record) {
+        const refreshedNetwork = udpTransport?.getDeviceDiagnosticNetwork?.(record.owner.deviceId, {
+            salt: record.leaseId
+        });
+        if (refreshedNetwork?.evidence
+                === 'authenticated-udp-endpoint-rendezvous-observed'
+            || record.network?.evidence
+                !== 'authenticated-udp-endpoint-rendezvous-observed') {
+            record.network = refreshedNetwork || record.network;
+        }
+        return {
+            ok: record.state !== 'failed',
+            leaseId: record.leaseId,
+            state: record.state,
+            phase: record.phase,
+            startedAt: record.startedAt,
+            updatedAt: record.updatedAt,
+            expiresAt: record.expiresAt,
+            completedAt: record.completedAt || '',
+            error: safeString(record.error, 240),
+            owner: {
+                deviceId: record.owner.deviceId,
+                streamId: record.owner.streamId,
+                streamCommandId: record.owner.streamCommandId,
+                captureGeneration: record.owner.captureGeneration,
+                monitorIndex: record.owner.monitorIndex
+            },
+            network: record.network,
+            baseline: { ...record.baseline },
+            frames: record.frames.map(frame => ({ ...frame })),
+            cleanup: record.cleanup.map(entry => ({ ...entry }))
+        };
+    }
+
+    function getTransportDiagnostic(leaseId, token) {
+        const record = transportDiagnostics.get(safeString(leaseId, 128));
+        if (!record || !diagnosticSecretEquals(record.token, token)) {
+            return { ok: false, error: 'transport-diagnostic-not-found' };
+        }
+        return serializeTransportDiagnostic(record);
+    }
+
+    function diagnosticSecretEquals(expected, provided) {
+        const expectedHash = crypto.createHash('sha256').update(String(expected || '')).digest();
+        const providedHash = crypto.createHash('sha256').update(String(provided || '')).digest();
+        return crypto.timingSafeEqual(expectedHash, providedHash);
+    }
+
+    async function sendTransportDiagnosticCommand(record, operation, phase = record.phase) {
+        const device = devices.get(record.owner.deviceId);
+        if (!device?.connected || device.sessionId !== record.owner.sessionId) {
+            return { ok: false, error: 'transport-diagnostic-device-disconnected' };
+        }
+        if (operation !== 'release' && !transportDiagnosticOwnerMatches(record, device)) {
+            return { ok: false, error: 'transport-diagnostic-owner-changed' };
+        }
+        const commandId = crypto.randomUUID();
+        const waiter = waitForCommandResult(device, commandId, transportDiagnosticCommandTimeoutMs);
+        const queued = sendCommand(device.deviceId, {
+            commandId,
+            command: 'transport.diagnostic',
+            payload: {
+                operation,
+                leaseId: record.leaseId,
+                token: record.token,
+                streamId: record.owner.streamId,
+                streamCommandId: record.owner.streamCommandId,
+                captureGeneration: record.owner.captureGeneration,
+                monitorIndex: record.owner.monitorIndex,
+                phase,
+                ttlMs: Math.max(0, Date.parse(record.expiresAt) - Date.now())
+            }
+        });
+        if (!queued.ok) {
+            failPendingCommandResultWaiter(commandId, queued.error);
+        }
+        const outcome = await waiter;
+        if (!outcome.ok || outcome.result?.ok === false) {
+            return {
+                ok: false,
+                error: safeString(outcome.error || outcome.result?.error, 240)
+                    || 'transport-diagnostic-agent-rejected'
+            };
+        }
+        return { ok: true };
+    }
+
+    function appendTransportDiagnosticCleanup(record, state, reason = '') {
+        record.cleanup.push({
+            at: new Date().toISOString(),
+            state,
+            reason: safeString(reason, 160)
+        });
+        if (record.cleanup.length > 16) record.cleanup.splice(0, record.cleanup.length - 16);
+        record.updatedAt = new Date().toISOString();
+    }
+
+    function clearTransportDiagnosticTimers(record) {
+        clearTimeout(record?.expiryTimer);
+        clearTimeout(record?.removalTimer);
+        if (record) {
+            record.expiryTimer = null;
+            record.removalTimer = null;
+        }
+    }
+
+    function removeTransportDiagnostic(record) {
+        if (!record) return;
+        clearTransportDiagnosticTimers(record);
+        if (transportDiagnostics.get(record.leaseId) === record) {
+            transportDiagnostics.delete(record.leaseId);
+        }
+        record.token = '';
+    }
+
+    function scheduleTransportDiagnosticRemoval(record) {
+        if (!record) return;
+        clearTimeout(record.expiryTimer);
+        clearTimeout(record.removalTimer);
+        record.expiryTimer = null;
+        record.removalTimer = setTimeout(() => {
+            removeTransportDiagnostic(record);
+        }, TRANSPORT_DIAGNOSTIC_RECORD_RETENTION_MS);
+        record.removalTimer.unref?.();
+    }
+
+    function pruneTransportDiagnosticRecords() {
+        const finalized = [...transportDiagnostics.values()]
+            .filter(record => record.state !== 'active'
+                && record.state !== 'acquiring'
+                && record.state !== 'expiring')
+            .sort((left, right) => Date.parse(left.updatedAt || '') - Date.parse(right.updatedAt || ''));
+        while (transportDiagnostics.size >= TRANSPORT_DIAGNOSTIC_MAX_RECORDS && finalized.length > 0) {
+            removeTransportDiagnostic(finalized.shift());
+        }
+    }
+
+    async function expireTransportDiagnostic(record, reason = 'ttl-expired') {
+        if (!record || record.state !== 'active') return;
+        if (record.operationInFlight === true) {
+            record.expiryTimer = setTimeout(() => {
+                void expireTransportDiagnostic(record, reason);
+            }, 250);
+            record.expiryTimer.unref?.();
+            return;
+        }
+        record.operationInFlight = true;
+        record.state = 'expiring';
+        appendTransportDiagnosticCleanup(record, 'release-requested', reason);
+        try {
+            const released = await sendTransportDiagnosticCommand(record, 'release');
+            record.state = reason === 'ttl-expired' ? 'expired' : 'aborted';
+            record.error = released.ok ? '' : released.error;
+            record.completedAt = new Date().toISOString();
+            appendTransportDiagnosticCleanup(
+                record,
+                released.ok ? 'agent-released' : 'agent-release-unconfirmed',
+                released.error);
+        } finally {
+            record.operationInFlight = false;
+            scheduleTransportDiagnosticRemoval(record);
+        }
+    }
+
+    function abortTransportDiagnosticsForDevice(device, reason) {
+        for (const record of transportDiagnostics.values()) {
+            if (!['active', 'acquiring', 'expiring'].includes(record.state)
+                || record.owner.deviceId !== device?.deviceId
+                || record.owner.sessionId !== device?.sessionId) {
+                continue;
+            }
+            clearTimeout(record.expiryTimer);
+            record.state = 'aborted';
+            record.error = safeString(reason, 160) || 'device-disconnected';
+            record.completedAt = new Date().toISOString();
+            appendTransportDiagnosticCleanup(record, 'connection-closed', record.error);
+            scheduleTransportDiagnosticRemoval(record);
+        }
+    }
+
+    async function startTransportDiagnostic(deviceId, ttlMs = 150_000, options = {}) {
+        const requestSignal = options?.signal;
+        const requestAborted = () => requestSignal?.aborted === true;
+        const normalizedDeviceId = safeString(deviceId, 160);
+        const device = devices.get(normalizedDeviceId);
+        const owner = currentTransportDiagnosticOwner(device);
+        if (!owner) {
+            return { ok: false, error: 'transport-diagnostic-current-h264-stream-required' };
+        }
+        if (observedTransportPath(device.latestLiveFrame) !== 'direct'
+            || safeString(device.latestLiveFrame?.frameTransportActive, 20).toLowerCase() !== 'direct') {
+            return { ok: false, error: 'transport-diagnostic-direct-start-required' };
+        }
+        if (transportDiagnosticStartingDevices.has(normalizedDeviceId)) {
+            return { ok: false, error: 'transport-diagnostic-device-lease-active' };
+        }
+        const existingLease = [...transportDiagnostics.values()].some(existing =>
+            ['active', 'acquiring', 'expiring'].includes(existing.state)
+            && existing.owner.deviceId === owner.deviceId);
+        if (existingLease) {
+            return { ok: false, error: 'transport-diagnostic-device-lease-active' };
+        }
+        transportDiagnosticStartingDevices.add(normalizedDeviceId);
+        try {
+            const refreshedDiagnosticNetwork =
+                await udpTransport?.refreshDeviceDiagnosticNetwork?.(
+                    owner.deviceId,
+                    { timeoutMs: 3_000 });
+            if (requestAborted()) {
+                return { ok: false, error: 'transport-diagnostic-request-aborted' };
+            }
+            const physicalNetwork = udpTransport?.getDeviceDiagnosticNetwork?.(
+                owner.deviceId,
+                { salt: 'transport-diagnostic-preflight' }) || {};
+            if (refreshedDiagnosticNetwork !== true
+                || physicalNetwork.evidence
+                    !== 'authenticated-udp-endpoint-rendezvous-observed'
+                || physicalNetwork.endpointAuthenticated !== true
+                || physicalNetwork.clientAddressPublic !== true
+                || physicalNetwork.hubAddressPublic !== true) {
+                return {
+                    ok: false,
+                    error: 'transport-diagnostic-fresh-rendezvous-egress-required'
+                };
+            }
+            if (physicalNetwork.differentPublicEgress !== true) {
+                return {
+                    ok: false,
+                    error: 'transport-diagnostic-distinct-public-egress-required'
+                };
+            }
+            const currentDevice = devices.get(normalizedDeviceId);
+            const refreshedOwner = currentTransportDiagnosticOwner(currentDevice);
+            if (!transportDiagnosticOwnersEqual(owner, refreshedOwner)
+                || observedTransportPath(currentDevice?.latestLiveFrame) !== 'direct'
+                || safeString(currentDevice?.latestLiveFrame?.frameTransportActive, 20).toLowerCase() !== 'direct') {
+                return { ok: false, error: 'transport-diagnostic-owner-changed' };
+            }
+            const concurrentLease = [...transportDiagnostics.values()].some(existing =>
+                ['active', 'acquiring', 'expiring'].includes(existing.state)
+                && existing.owner.deviceId === owner.deviceId);
+            if (concurrentLease) {
+                return { ok: false, error: 'transport-diagnostic-device-lease-active' };
+            }
+            pruneTransportDiagnosticRecords();
+            if (transportDiagnostics.size >= TRANSPORT_DIAGNOSTIC_MAX_RECORDS) {
+                return { ok: false, error: 'transport-diagnostic-capacity-reached' };
+            }
+
+            const boundedTtlMs = clampNumber(
+                ttlMs,
+                TRANSPORT_DIAGNOSTIC_MIN_TTL_MS,
+                TRANSPORT_DIAGNOSTIC_MAX_TTL_MS,
+                150_000);
+            const now = new Date();
+            const leaseId = crypto.randomUUID();
+            const token = crypto.randomBytes(32).toString('base64url');
+            const currentFrame = currentDevice.latestLiveFrame;
+            const udpStatus = udpTransport?.getDeviceStatus?.(owner.deviceId) || {};
+            const hubAddressObservedAt = safeString(
+                physicalNetwork.hubAddressObservedAt,
+                80);
+            const record = {
+                leaseId,
+                token,
+                owner,
+                phase: 'direct',
+                phaseStartedAt: '',
+                state: 'acquiring',
+                operationInFlight: true,
+                startedAt: now.toISOString(),
+                updatedAt: now.toISOString(),
+                expiresAt: new Date(now.getTime() + boundedTtlMs).toISOString(),
+                completedAt: '',
+                error: '',
+                hubAddressObservedAt,
+                baseline: {
+                    observedAt: safeString(currentFrame.receivedAt, 80),
+                    frameSeq: optionalFiniteNumber(currentFrame.frameSeq),
+                    switchCount: optionalFiniteNumber(currentFrame.frameTransportSwitchCount),
+                    agentQueueDropped: optionalFiniteNumber(currentFrame.nativeOutputQueueDroppedCount),
+                    hubIngressDropped: optionalFiniteNumber(currentFrame.hubIngressDropped),
+                    udpIncompleteFrames: optionalFiniteNumber(udpStatus.droppedFrames),
+                    hubIngressCounterEpochHash: transportDiagnosticIdentifierHash(
+                        currentFrame.hubIngressCounterEpoch,
+                        leaseId),
+                    udpCounterEpochHash: transportDiagnosticIdentifierHash(
+                        udpStatus.sessionId,
+                        leaseId),
+                    agentQueueTelemetryAvailable:
+                        currentFrame.nativeOutputQueueTelemetryAvailable === true,
+                    hubIngressTelemetryAvailable:
+                        currentFrame.hubIngressTelemetryAvailable === true
+                        && !!currentFrame.hubIngressCounterEpoch,
+                    udpTelemetryAvailable:
+                        optionalFiniteNumber(udpStatus.droppedFrames) !== null
+                        && !!udpStatus.sessionId
+                },
+                frames: [],
+                cleanup: [],
+                network: udpTransport?.getDeviceDiagnosticNetwork?.(owner.deviceId, {
+                    salt: leaseId
+                }) || {
+                    evidence: 'unavailable',
+                    differentPublicEgress: null,
+                    hubAddressObservedAt
+                },
+                expiryTimer: null,
+                removalTimer: null
+            };
+            transportDiagnostics.set(leaseId, record);
+            const acquired = await sendTransportDiagnosticCommand(record, 'acquire', 'direct');
+            record.operationInFlight = false;
+            if (!acquired.ok || record.state !== 'acquiring') {
+                const acquireError = acquired.ok
+                    ? safeString(record.error, 240) || 'transport-diagnostic-acquire-interrupted'
+                    : acquired.error;
+                record.error = acquireError;
+                record.completedAt = new Date().toISOString();
+                appendTransportDiagnosticCleanup(record, 'acquire-failed', record.error);
+                appendTransportDiagnosticCleanup(
+                    record,
+                    'release-requested',
+                    'acquire-outcome-uncertain');
+                record.operationInFlight = true;
+                let released;
+                try {
+                    released = await sendTransportDiagnosticCommand(record, 'release');
+                } catch (error) {
+                    released = {
+                        ok: false,
+                        error: safeString(error instanceof Error ? error.message : error, 240)
+                            || 'transport-diagnostic-agent-release-failed'
+                    };
+                } finally {
+                    record.operationInFlight = false;
+                }
+                appendTransportDiagnosticCleanup(
+                    record,
+                    released.ok ? 'agent-released' : 'agent-release-unconfirmed',
+                    released.error);
+                record.state = 'failed';
+                record.completedAt = new Date().toISOString();
+                const failed = { ...serializeTransportDiagnostic(record), token: '' };
+                removeTransportDiagnostic(record);
+                return failed;
+            }
+            record.state = 'active';
+            record.phaseStartedAt = new Date().toISOString();
+            record.updatedAt = record.phaseStartedAt;
+            appendTransportDiagnosticCleanup(record, 'lease-acquired');
+            if (requestAborted()) {
+                await expireTransportDiagnostic(record, 'start-request-aborted');
+                return { ok: false, error: 'transport-diagnostic-request-aborted' };
+            }
+            const remainingTtlMs = Math.max(1, Date.parse(record.expiresAt) - Date.now());
+            record.expiryTimer = setTimeout(() => {
+                void expireTransportDiagnostic(record, 'ttl-expired');
+            }, remainingTtlMs);
+            record.expiryTimer.unref?.();
+            return { ...serializeTransportDiagnostic(record), token };
+        } finally {
+            transportDiagnosticStartingDevices.delete(normalizedDeviceId);
+        }
+    }
+
+    async function setTransportDiagnosticPhase(leaseId, token, phase) {
+        const record = transportDiagnostics.get(safeString(leaseId, 128));
+        const normalizedPhase = safeString(phase, 32).toLowerCase();
+        if (!record || !diagnosticSecretEquals(record.token, token)) {
+            return { ok: false, error: 'transport-diagnostic-not-found' };
+        }
+        if (record.state !== 'active') {
+            return { ok: false, error: 'transport-diagnostic-not-active' };
+        }
+        if (record.operationInFlight === true) {
+            return { ok: false, error: 'transport-diagnostic-operation-in-flight' };
+        }
+        if (!TRANSPORT_DIAGNOSTIC_PHASES.includes(normalizedPhase)) {
+            return { ok: false, error: 'transport-diagnostic-phase-invalid' };
+        }
+        const currentIndex = TRANSPORT_DIAGNOSTIC_PHASES.indexOf(record.phase);
+        const nextIndex = TRANSPORT_DIAGNOSTIC_PHASES.indexOf(normalizedPhase);
+        const currentObserved = record.frames.some(frame => frame.phase === record.phase && frame.accepted === true);
+        if (nextIndex !== currentIndex + 1 || !currentObserved) {
+            return { ok: false, error: 'transport-diagnostic-phase-order-required' };
+        }
+        record.operationInFlight = true;
+        try {
+            const updated = await sendTransportDiagnosticCommand(record, 'set-phase', normalizedPhase);
+            if (!updated.ok) {
+                record.error = updated.error;
+                record.updatedAt = new Date().toISOString();
+                return { ok: false, error: updated.error };
+            }
+            if (record.state !== 'active') {
+                return { ok: false, error: 'transport-diagnostic-interrupted' };
+            }
+            record.phase = normalizedPhase;
+            record.phaseStartedAt = new Date().toISOString();
+            record.updatedAt = record.phaseStartedAt;
+            return serializeTransportDiagnostic(record);
+        } finally {
+            record.operationInFlight = false;
+        }
+    }
+
+    async function stopTransportDiagnostic(leaseId, token, reason = 'runner-complete') {
+        const record = transportDiagnostics.get(safeString(leaseId, 128));
+        if (!record || !diagnosticSecretEquals(record.token, token)) {
+            return { ok: false, error: 'transport-diagnostic-not-found' };
+        }
+        if (record.state !== 'active') return serializeTransportDiagnostic(record);
+        if (record.operationInFlight === true) {
+            return { ok: false, error: 'transport-diagnostic-operation-in-flight' };
+        }
+        clearTimeout(record.expiryTimer);
+        record.operationInFlight = true;
+        try {
+            appendTransportDiagnosticCleanup(record, 'release-requested', reason);
+            const released = await sendTransportDiagnosticCommand(record, 'release');
+            record.state = released.ok ? 'completed' : 'failed';
+            record.error = released.ok ? '' : released.error;
+            record.completedAt = new Date().toISOString();
+            appendTransportDiagnosticCleanup(
+                record,
+                released.ok ? 'agent-released' : 'agent-release-unconfirmed',
+                released.error);
+            const serialized = serializeTransportDiagnostic(record);
+            scheduleTransportDiagnosticRemoval(record);
+            return serialized;
+        } finally {
+            record.operationInFlight = false;
+        }
+    }
+
+    function recordTransportDiagnosticFrame(device, message, payload, frame) {
+        if (transportDiagnostics.size === 0 || message.transportDiagnosticApplied !== true) {
+            return;
+        }
+        const leaseId = safeString(message.transportDiagnosticLeaseId, 128);
+        const phase = safeString(message.transportDiagnosticPhase, 32).toLowerCase();
+        if (!leaseId) return;
+        const record = transportDiagnostics.get(leaseId);
+        if (!record
+            || record.state !== 'active'
+            || record.phase !== phase
+            || !transportDiagnosticOwnerMatches(record, device)
+            || frame.streamId !== record.owner.streamId
+            || frame.commandId !== record.owner.streamCommandId
+            || frame.captureGeneration !== record.owner.captureGeneration
+            || frame.monitorIndex !== record.owner.monitorIndex
+            || safeString(frame.mimeType, 80).toLowerCase() !== 'video/h264') {
+            return;
+        }
+        const expectedPath = expectedTransportForDiagnosticPhase(phase);
+        const h264 = inspectAnnexBH264(payload);
+        const agentPath = safeString(frame.frameTransportActive, 20).toLowerCase();
+        const hubObservedPath = observedTransportPath(frame);
+        const frameSeq = optionalFiniteNumber(frame.frameSeq);
+        const switchCount = optionalFiniteNumber(message.frameTransportSwitchCount);
+        const lastAcceptedFrame = [...record.frames]
+            .reverse()
+            .find(item => item.accepted === true);
+        const previousFrameSeq = optionalFiniteNumber(
+            lastAcceptedFrame?.frameSeq ?? record.baseline?.frameSeq);
+        const previousSwitchCount = optionalFiniteNumber(
+            lastAcceptedFrame?.switchCount ?? record.baseline?.switchCount);
+        const sequenceAdvanced = frameSeq !== null
+            && (previousFrameSeq === null || frameSeq > previousFrameSeq);
+        const switchAdvanced = switchCount !== null
+            && (lastAcceptedFrame
+                ? previousSwitchCount !== null && switchCount > previousSwitchCount
+                : previousSwitchCount === null || switchCount >= previousSwitchCount);
+        const agentQueueDepth = optionalFiniteNumber(message.nativeOutputQueueDepth);
+        const agentQueueBytes = optionalFiniteNumber(message.nativeOutputQueueBytes);
+        const agentQueueDropped = optionalFiniteNumber(message.nativeOutputQueueDroppedCount);
+        const hubIngressDropped = optionalFiniteNumber(message.hubIngressDropped);
+        const udpIncompleteFrames = optionalFiniteNumber(message.udpIncompleteFrames);
+        const hubIngressCounterEpochHash = transportDiagnosticIdentifierHash(
+            message.hubIngressCounterEpoch,
+            record.leaseId);
+        const agentQueueTelemetryAvailable = agentQueueDepth !== null
+            && agentQueueBytes !== null
+            && agentQueueDropped !== null;
+        const hubIngressTelemetryAvailable = hubIngressDropped !== null
+            && !!hubIngressCounterEpochHash;
+        const udpTelemetryAvailable = phase !== 'p2p' || udpIncompleteFrames !== null;
+        const phaseLatencyMs = Math.max(
+            0,
+            Date.parse(frame.receivedAt || '') - Date.parse(record.phaseStartedAt || ''));
+        const accepted = agentPath === expectedPath
+            && hubObservedPath === expectedPath
+            && frame.isKeyFrame === true
+            && h264.annexB
+            && h264.hasIdr
+            && h264.hasSps
+            && h264.hasPps
+            && h264.nalOrderValid
+            && sequenceAdvanced
+            && switchAdvanced
+            && agentQueueTelemetryAvailable
+            && hubIngressTelemetryAvailable
+            && udpTelemetryAvailable
+            && Number.isFinite(phaseLatencyMs);
+        if (record.frames.some(item => item.phase === phase && item.accepted === true)) return;
+        const observation = {
+            phase,
+            expectedPath,
+            actualPath: agentPath,
+            hubObservedPath,
+            protocol: safeString(frame.frameTransportProtocol, 20),
+            transport: safeString(frame.transport, 32),
+            reason: safeString(frame.frameTransportReason, 160),
+            receivedAt: frame.receivedAt,
+            frameSeq,
+            byteLength: frame.byteLength,
+            contentHash: safeString(frame.contentHash, 128),
+            isKeyFrame: frame.isKeyFrame === true,
+            annexB: h264.annexB,
+            hasIdr: h264.hasIdr,
+            hasSps: h264.hasSps,
+            hasPps: h264.hasPps,
+            nalOrderValid: h264.nalOrderValid,
+            switchCount,
+            tcpFailureCount: frame.frameTransportTcpFailureCount,
+            phaseLatencyMs,
+            sequenceAdvanced,
+            switchAdvanced,
+            agentQueueDepth,
+            agentQueueBytes,
+            agentQueueDropped,
+            hubIngressDropped,
+            udpIncompleteFrames,
+            hubIngressCounterEpochHash,
+            agentQueueTelemetryAvailable,
+            hubIngressTelemetryAvailable,
+            udpTelemetryAvailable,
+            accepted
+        };
+        if (accepted) {
+            record.frames = record.frames.filter(item => item.phase !== phase);
+            record.frames.push(observation);
+        } else {
+            const rejectedIndex = record.frames.findIndex(item =>
+                item.phase === phase && item.accepted !== true);
+            if (rejectedIndex >= 0) record.frames[rejectedIndex] = observation;
+            else record.frames.push(observation);
+        }
+        if (record.frames.length > TRANSPORT_DIAGNOSTIC_PHASES.length * 2) {
+            record.frames = record.frames.filter(item => item.accepted === true)
+                .concat(record.frames.filter(item => item.accepted !== true)
+                    .slice(-TRANSPORT_DIAGNOSTIC_PHASES.length));
+        }
+        record.updatedAt = new Date().toISOString();
+    }
+
     function makeSyntheticFrame(device, streamId, mode = 'thumbnail', options = {}) {
         const now = new Date().toISOString();
         const descriptor = buildRemoteFrameTransferDescriptor(mode, mode === 'thumbnail' ? 'thumbnail' : DEFAULT_REMOTE_FRAME_MODE);
@@ -3117,9 +3857,10 @@ export function createRemoteHub(options = {}) {
             return;
         }
 
-        device.connected = false;
-        device.socket = null;
-        udpTransport?.unregisterDevice?.(deviceId, device.sessionId);
+        device.connected = false;
+        device.socket = null;
+        abortTransportDiagnosticsForDevice(device, reason);
+        udpTransport?.unregisterDevice?.(deviceId, device.sessionId);
         closeInputSocket(device, reason);
         closeFrameSocket(device, reason);
         device.disconnectedAt = new Date().toISOString();
@@ -3560,6 +4301,48 @@ export function createRemoteHub(options = {}) {
                 ?? result.HubForwardedAtEpochMs
                 ?? pending?.hubForwardedAtEpochMs
                 ?? 0) || 0,
+            duplicate: message.duplicate === true
+                || message.Duplicate === true
+                || result.duplicate === true
+                || result.Duplicate === true,
+            nativeInputBackend: safeString(
+                message.nativeInputBackend
+                || message.NativeInputBackend
+                || result.nativeInputBackend
+                || result.NativeInputBackend,
+                80),
+            nativeEventsRequested: Math.max(0, Number(
+                message.nativeEventsRequested
+                ?? message.NativeEventsRequested
+                ?? result.nativeEventsRequested
+                ?? result.NativeEventsRequested
+                ?? 0) || 0),
+            nativeEventsAccepted: Math.max(0, Number(
+                message.nativeEventsAccepted
+                ?? message.NativeEventsAccepted
+                ?? result.nativeEventsAccepted
+                ?? result.NativeEventsAccepted
+                ?? 0) || 0),
+            hookEventsObserved: Math.max(0, Number(
+                message.hookEventsObserved
+                ?? message.HookEventsObserved
+                ?? result.hookEventsObserved
+                ?? result.HookEventsObserved
+                ?? 0) || 0),
+            hookEventsBlocked: Math.max(0, Number(
+                message.hookEventsBlocked
+                ?? message.HookEventsBlocked
+                ?? result.hookEventsBlocked
+                ?? result.HookEventsBlocked
+                ?? 0) || 0),
+            focusChanged: message.focusChanged === true
+                || message.FocusChanged === true
+                || result.focusChanged === true
+                || result.FocusChanged === true,
+            inputDiagnostic: message.inputDiagnostic === true
+                || message.InputDiagnostic === true
+                || result.inputDiagnostic === true
+                || result.InputDiagnostic === true,
             fallback: pending?.fallback === true,
             hubAcknowledgedAtEpochMs: Date.now()
         };
@@ -4408,10 +5191,17 @@ export function createRemoteHub(options = {}) {
             nativeOutputQueueHighWatermark: Number.isFinite(Number(message.nativeOutputQueueHighWatermark)) ? Number(message.nativeOutputQueueHighWatermark) : 0,
             nativeOutputQueueDroppedCount: Number.isFinite(Number(message.nativeOutputQueueDroppedCount)) ? Number(message.nativeOutputQueueDroppedCount) : 0,
             nativeOutputQueueAwaitingKeyFrame: message.nativeOutputQueueAwaitingKeyFrame === true,
+            nativeOutputQueueTelemetryAvailable:
+                optionalFiniteNumber(message.nativeOutputQueueDepth) !== null
+                && optionalFiniteNumber(message.nativeOutputQueueBytes) !== null
+                && optionalFiniteNumber(message.nativeOutputQueueDroppedCount) !== null,
             nativeCaptureTelemetryAt: safeString(message.nativeCaptureTelemetryAt, 80),
             droppedByAgent: Number.isFinite(Number(message.droppedByAgent)) ? Number(message.droppedByAgent) : 0,
             hubIngressDropped: Number.isFinite(Number(message.hubIngressDropped)) ? Number(message.hubIngressDropped) : 0,
             udpIncompleteFrames: Number.isFinite(Number(message.udpIncompleteFrames)) ? Number(message.udpIncompleteFrames) : 0,
+            hubIngressTelemetryAvailable: optionalFiniteNumber(message.hubIngressDropped) !== null,
+            udpIncompleteTelemetryAvailable: optionalFiniteNumber(message.udpIncompleteFrames) !== null,
+            hubIngressCounterEpoch: safeString(message.hubIngressCounterEpoch, 160),
             hardwareEncoder: safeString(message.hardwareEncoder, 80),
             platformProfile: safeString(message.platformProfile, 80),
             monitorIndex: activeMonitorIndex,
@@ -4462,9 +5252,10 @@ export function createRemoteHub(options = {}) {
             frameTransportTcpFailureCount: Number.isFinite(Number(message.frameTransportTcpFailureCount)) ? Number(message.frameTransportTcpFailureCount) : 0,
             sameContentStreak,
             payload,
-            accessToken: createFrameAccessToken()
-        };
-        streamState.latestFrame = device.latestLiveFrame;
+            accessToken: createFrameAccessToken()
+        };
+        recordTransportDiagnosticFrame(device, message, payload, device.latestLiveFrame);
+        streamState.latestFrame = device.latestLiveFrame;
         rememberRecentFramePayload(device, 'live', device.latestLiveFrame);
         emitFrame({
             kind: 'live',
@@ -4659,7 +5450,8 @@ export function createRemoteHub(options = {}) {
         if (frameKind === 'stream' || frameKind === 'live' || header.type === 'stream.binary') {
             applyLiveFrame(device, {
                 ...header,
-                hubIngressDropped: Number(state.binaryQueueDrops || 0)
+                hubIngressDropped: Number(state.binaryQueueDrops || 0),
+                hubIngressCounterEpoch: state.binaryQueueEpoch
             }, framePayload, binaryTransport);
             return;
         }
@@ -4700,10 +5492,11 @@ export function createRemoteHub(options = {}) {
             lastFrameAt: new Date().toISOString(),
             framesReceived: Number(device.udp?.framesReceived || 0) + 1
         };
-        return applyLiveFrame(device, {
-            ...header,
-            transport: 'udp-p2p'
-        }, payload, 'udp-p2p');
+        return applyLiveFrame(device, {
+            ...header,
+            transport: 'udp-p2p',
+            hubIngressCounterEpoch: sessionId
+        }, payload, 'udp-p2p');
     }
 
     function dropQueuedAgentBinaryFrame(state) {
@@ -5033,9 +5826,10 @@ export function createRemoteHub(options = {}) {
             binaryQueue: [],
             binaryQueueDraining: false,
             binaryQueueScheduled: false,
-            binaryQueueSocket: null,
-            binaryQueueDrops: 0,
-            closed: false
+            binaryQueueSocket: null,
+            binaryQueueDrops: 0,
+            binaryQueueEpoch: crypto.randomUUID(),
+            closed: false
         };
 
         const helloTimer = setTimeout(() => {
@@ -5193,9 +5987,10 @@ export function createRemoteHub(options = {}) {
             binaryQueue: [],
             binaryQueueDraining: false,
             binaryQueueScheduled: false,
-            binaryQueueSocket: null,
-            binaryQueueDrops: 0,
-            closed: false
+            binaryQueueSocket: null,
+            binaryQueueDrops: 0,
+            binaryQueueEpoch: crypto.randomUUID(),
+            closed: false
         };
 
         const helloTimer = setTimeout(() => {
@@ -5419,8 +6214,9 @@ export function createRemoteHub(options = {}) {
         return getStatus({ includeSecrets: false });
     }
 
-    async function close() {
+    async function close() {
         for (const device of devices.values()) {
+            abortTransportDiagnosticsForDevice(device, 'hub-shutdown');
             failAllPendingTasks(device, 'hub-shutdown');
             failAllPendingInputFallbacks(device, 'hub-shutdown');
             failPendingCommandResultWaiters(device, 'hub-shutdown');
@@ -5472,10 +6268,11 @@ export function createRemoteHub(options = {}) {
 
     function disconnectDevice(deviceId, reason = 'manager-disconnect') {
         const device = devices.get(String(deviceId || ''));
-        if (device?.synthetic === true) {
-            device.connected = false;
-            device.disconnectedAt = new Date().toISOString();
-            device.lastDisconnectReason = reason;
+        if (device?.synthetic === true) {
+            device.connected = false;
+            device.disconnectedAt = new Date().toISOString();
+            device.lastDisconnectReason = reason;
+            abortTransportDiagnosticsForDevice(device, reason);
             deactivateDeviceLiveStreams(device, reason, device.disconnectedAt);
             failAllPendingTasks(device, 'device-disconnected');
             failAllPendingInputFallbacks(device, 'device-disconnected');
@@ -7529,6 +8326,10 @@ export function createRemoteHub(options = {}) {
         stopLiveStream,
         pauseLiveCapture,
         resumeLiveCapture,
+        startTransportDiagnostic,
+        getTransportDiagnostic,
+        setTransportDiagnosticPhase,
+        stopTransportDiagnostic,
         startAudioStream,
         stopAudioStream,
         getDeviceLiveFrame,