@livedesk/hub 0.1.25 → 0.1.27

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;
 }
@@ -1528,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 || (() => {});
@@ -1631,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;
@@ -2266,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);
@@ -3135,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();
@@ -3578,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()
         };
@@ -3924,6 +4689,10 @@ export function createRemoteHub(options = {}) {
                 ? message.nativeEncoderHardwareAccelerated
                 : null,
             nativeEncoderHardwareQueryStatus: safeString(message.nativeEncoderHardwareQueryStatus, 80),
+            nativeCaptureDisplayId: Number.isSafeInteger(Number(message.nativeCaptureDisplayId))
+                && Number(message.nativeCaptureDisplayId) > 0
+                ? Number(message.nativeCaptureDisplayId)
+                : 0,
             nativeCaptureFps: Number.isFinite(Number(message.nativeCaptureFps)) ? Number(message.nativeCaptureFps) : 0,
             nativeCompressionFps: Number.isFinite(Number(message.nativeCompressionFps)) ? Number(message.nativeCompressionFps) : 0,
             nativeEncodedFps: Number.isFinite(Number(message.nativeEncodedFps)) ? Number(message.nativeEncodedFps) : 0,
@@ -3981,7 +4750,7 @@ export function createRemoteHub(options = {}) {
         return true;
     }
 
-    function promotePendingLiveStream(device, streamState, message, transport) {
+    function matchPendingLiveStreamOwner(device, streamState, message, transport) {
         const pending = getPendingLiveStreamDescriptor(streamState);
         const commandId = safeString(message.commandId, 128);
         if (!pending || !commandId || commandId !== safeString(pending.commandId, 128)) {
@@ -3989,9 +4758,11 @@ export function createRemoteHub(options = {}) {
         }
         const messageCaptureGeneration = Number(message.captureGeneration || 0);
         const pendingCaptureGeneration = Number(pending.captureGeneration || 0);
-        if (messageCaptureGeneration > 0
-            && pendingCaptureGeneration > 0
-            && messageCaptureGeneration !== pendingCaptureGeneration) {
+        if (!Number.isSafeInteger(messageCaptureGeneration)
+            || messageCaptureGeneration <= 0
+            || !Number.isSafeInteger(pendingCaptureGeneration)
+            || pendingCaptureGeneration <= 0
+            || messageCaptureGeneration !== pendingCaptureGeneration) {
             emitRemoteEvent('RemoteLiveStreamOpenIgnored', device, {
                 reason: 'stale-pending-capture-generation',
                 streamId: streamState.streamId,
@@ -4030,6 +4801,27 @@ export function createRemoteHub(options = {}) {
             });
             return null;
         }
+        return {
+            pending,
+            commandId,
+            messageCaptureGeneration,
+            pendingCaptureGeneration,
+            pendingMonitorIndex
+        };
+    }
+
+    function promotePendingLiveStream(device, streamState, message, transport) {
+        const owner = matchPendingLiveStreamOwner(device, streamState, message, transport);
+        if (!owner) {
+            return null;
+        }
+        const {
+            pending,
+            commandId,
+            messageCaptureGeneration,
+            pendingCaptureGeneration,
+            pendingMonitorIndex
+        } = owner;
 
         const previousCommandId = safeString(streamState.commandId, 128);
         const transfer = buildRemoteFrameTransferDescriptorFromMessage(
@@ -4138,16 +4930,22 @@ export function createRemoteHub(options = {}) {
 
         const activatingPendingGeneration = isPendingGeneration && commandId !== activeCommandId;
         if (activatingPendingGeneration) {
-            const promoted = promotePendingLiveStream(device, streamState, message, transport);
-            if (!promoted) {
+            const owner = matchPendingLiveStreamOwner(device, streamState, message, transport);
+            if (!owner) {
                 return false;
             }
-            emitLiveStreamOpened(
-                device,
-                promoted.streamState,
-                promoted.transfer,
-                transport,
-                promoted.previousCommandId);
+            // stream.open travels on the manager connection while the binary
+            // first frame travels on a separate transport. Their arrival order
+            // is not defined. Keep the current generation and its last frame
+            // until the matching first real frame validates and commits the
+            // pending owner atomically.
+            emitRemoteEvent('RemoteLiveStreamOpenDeferred', device, {
+                streamId,
+                commandId,
+                captureGeneration: owner.messageCaptureGeneration,
+                monitorIndex: owner.pendingMonitorIndex,
+                transport
+            });
             return true;
         }
 
@@ -4224,8 +5022,8 @@ export function createRemoteHub(options = {}) {
         const commandId = safeString(message.commandId, 128);
         let streamState = getDeviceLiveStream(device, streamId);
         if (!streamState?.active) {
-            device.counters.liveFramesDropped += 1;
-            emitRemoteEvent('RemoteFrameDropped', device, {
+            device.counters.liveFramesDropped += 1;
+            emitRemoteEvent('RemoteFrameDropped', device, {
                 reason: 'stale-live-stream-frame',
                 streamId,
                 frameSeq: Number.isFinite(frameSeq) ? frameSeq : null,
@@ -4233,9 +5031,91 @@ export function createRemoteHub(options = {}) {
             });
             return false;
         }
+        const byteLength = normalizeFrameByteLength(framePayload, frameData);
+        const streamFrameSeq = Number.isFinite(Number(message.streamFrameSeq))
+            ? Number(message.streamFrameSeq)
+            : frameSeq;
+        if (byteLength <= 0
+            || byteLength > MAX_STREAM_BINARY_BYTES
+            || !Number.isSafeInteger(frameSeq)
+            || frameSeq <= 0
+            || !Number.isSafeInteger(streamFrameSeq)
+            || streamFrameSeq <= 0) {
+            device.counters.liveFramesDropped += 1;
+            emitRemoteEvent('RemoteFrameDropped', device, {
+                reason: 'invalid-live-frame',
+                streamId,
+                commandId,
+                captureGeneration: Number(message.captureGeneration || 0),
+                monitorIndex: parseExactLiveStreamMonitorIndex(message.monitorIndex),
+                frameSeq: Number.isFinite(frameSeq) ? frameSeq : null,
+                transport
+            });
+            return false;
+        }
+        const payload = buildFramePayloadBuffer(framePayload, frameData);
+        if (payload.length <= 0 || payload.length > MAX_STREAM_BINARY_BYTES) {
+            device.counters.liveFramesDropped += 1;
+            emitRemoteEvent('RemoteFrameDropped', device, {
+                reason: 'invalid-live-frame-payload',
+                streamId,
+                commandId,
+                captureGeneration: Number(message.captureGeneration || 0),
+                monitorIndex: parseExactLiveStreamMonitorIndex(message.monitorIndex),
+                frameSeq,
+                transport
+            });
+            return false;
+        }
         let activeCommandId = safeString(streamState.commandId, 128);
-        let pendingCommandId = safeString(getPendingLiveStreamDescriptor(streamState)?.commandId, 128);
+        const pendingDescriptor = getPendingLiveStreamDescriptor(streamState);
+        let pendingCommandId = safeString(pendingDescriptor?.commandId, 128);
         if (pendingCommandId && commandId === pendingCommandId && commandId !== activeCommandId) {
+            if (!matchPendingLiveStreamOwner(device, streamState, message, `${transport}-implicit`)) {
+                return false;
+            }
+            const pendingFrameMode = safeString(
+                message.frameMode
+                    || message.mode
+                    || pendingDescriptor?.frameMode
+                    || pendingDescriptor?.mode,
+                40).toLowerCase();
+            const pendingMimeType = safeString(
+                message.mimeType
+                    || message.format
+                    || pendingDescriptor?.compression,
+                80).toLowerCase();
+            const pendingCodec = safeString(
+                message.codec
+                    || pendingDescriptor?.codec
+                    || pendingDescriptor?.encoding,
+                40).toLowerCase();
+            const requiresH264KeyFrame = pendingFrameMode === 'mode3-h264-hw'
+                || pendingMimeType.includes('h264')
+                || pendingMimeType.includes('avc')
+                || pendingCodec.includes('h264')
+                || pendingCodec.includes('avc');
+            const isH264KeyFrame = message.isKeyFrame === true
+                || safeString(message.chunkType, 20).toLowerCase() === 'key';
+            const h264 = requiresH264KeyFrame ? inspectAnnexBH264(payload) : null;
+            const independentlyDecodableH264KeyFrame = isH264KeyFrame
+                && h264?.annexB === true
+                && h264.hasSps === true
+                && h264.hasPps === true
+                && h264.hasIdr === true
+                && h264.nalOrderValid === true;
+            if (requiresH264KeyFrame && !independentlyDecodableH264KeyFrame) {
+                device.counters.liveFramesDropped += 1;
+                emitRemoteEvent('RemoteFrameDropped', device, {
+                    reason: 'pending-live-stream-decodable-keyframe-required',
+                    streamId,
+                    commandId,
+                    frameSeq,
+                    streamFrameSeq,
+                    transport
+                });
+                return false;
+            }
             const promoted = promotePendingLiveStream(device, streamState, message, `${transport}-implicit`);
             if (promoted) {
                 streamState = promoted.streamState;
@@ -4313,24 +5193,38 @@ export function createRemoteHub(options = {}) {
             return false;
         }
 
-        const byteLength = normalizeFrameByteLength(framePayload, frameData);
-        if ((!Buffer.isBuffer(framePayload) && !frameData)
-            || byteLength > MAX_STREAM_BINARY_BYTES
-            || !Number.isFinite(frameSeq)) {
-            device.counters.liveFramesDropped += 1;
-            emitRemoteEvent('RemoteFrameDropped', device, {
-                reason: 'invalid-live-frame',
-                streamId,
-                frameSeq: Number.isFinite(frameSeq) ? frameSeq : null,
-                transport
-            });
-            return false;
-        }
-
-        const mimeType = safeString(message.mimeType || message.format || 'image/jpeg', 80) || 'image/jpeg';
-        const capturedAt = safeString(message.capturedAt, 80) || device.lastSeenAt;
-        const payload = buildFramePayloadBuffer(framePayload, frameData);
-        const contentHash = buildFrameContentHash(message, payload);
+        const previousFrame = streamState.latestFrame;
+        const currentOwnerCommandId = commandId || activeCommandId;
+        const currentOwnerCaptureGeneration = activeCaptureGeneration || frameCaptureGeneration;
+        const previousStreamFrameSeq = Number(previousFrame?.streamFrameSeq ?? previousFrame?.frameSeq);
+        const sameFrameOwner = previousFrame
+            && safeString(previousFrame.streamId, 128) === streamId
+            && safeString(previousFrame.commandId, 128) === currentOwnerCommandId
+            && Number(previousFrame.captureGeneration || 0) === currentOwnerCaptureGeneration
+            && parseExactLiveStreamMonitorIndex(previousFrame.monitorIndex) === frameMonitorIndex;
+        if (sameFrameOwner
+            && Number.isSafeInteger(previousStreamFrameSeq)
+            && streamFrameSeq <= previousStreamFrameSeq) {
+            device.counters.liveFramesDropped += 1;
+            emitRemoteEvent('RemoteFrameDropped', device, {
+                reason: streamFrameSeq === previousStreamFrameSeq
+                    ? 'duplicate-live-stream-frame'
+                    : 'out-of-order-live-stream-frame',
+                streamId,
+                commandId: currentOwnerCommandId,
+                captureGeneration: currentOwnerCaptureGeneration,
+                monitorIndex: frameMonitorIndex,
+                frameSeq,
+                streamFrameSeq,
+                previousStreamFrameSeq,
+                transport
+            });
+            return false;
+        }
+
+        const mimeType = safeString(message.mimeType || message.format || 'image/jpeg', 80) || 'image/jpeg';
+        const capturedAt = safeString(message.capturedAt, 80) || device.lastSeenAt;
+        const contentHash = buildFrameContentHash(message, payload);
         const sameContentStreak = computeSameContentStreak(streamState.latestFrame, contentHash);
         const transfer = buildRemoteFrameTransferDescriptorFromMessage(message, streamState.mode || DEFAULT_REMOTE_FRAME_MODE);
         if (streamState.open !== true) {
@@ -4364,7 +5258,7 @@ export function createRemoteHub(options = {}) {
         device.latestLiveFrame = {
             streamId,
             frameSeq,
-            streamFrameSeq: Number.isFinite(Number(message.streamFrameSeq)) ? Number(message.streamFrameSeq) : frameSeq,
+            streamFrameSeq,
             commandId: commandId || activeCommandId,
             sessionId: device.sessionId,
             captureGeneration: activeCaptureGeneration || frameCaptureGeneration,
@@ -4410,6 +5304,10 @@ export function createRemoteHub(options = {}) {
                 ? message.nativeEncoderHardwareAccelerated
                 : null,
             nativeEncoderHardwareQueryStatus: safeString(message.nativeEncoderHardwareQueryStatus, 80),
+            nativeCaptureDisplayId: Number.isSafeInteger(Number(message.nativeCaptureDisplayId))
+                && Number(message.nativeCaptureDisplayId) > 0
+                ? Number(message.nativeCaptureDisplayId)
+                : 0,
             nativeCaptureFps: Number.isFinite(Number(message.nativeCaptureFps)) ? Number(message.nativeCaptureFps) : 0,
             nativeCompressionFps: Number.isFinite(Number(message.nativeCompressionFps)) ? Number(message.nativeCompressionFps) : 0,
             nativeEncodedFps: Number.isFinite(Number(message.nativeEncodedFps)) ? Number(message.nativeEncodedFps) : 0,
@@ -4426,10 +5324,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,
@@ -4480,9 +5385,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',
@@ -4596,7 +5502,7 @@ export function createRemoteHub(options = {}) {
         return true;
     }
 
-    function applyAudioStatus(device, message, framePayload, transport = 'binary') {
+    function applyAudioStatus(device, message, framePayload, transport = 'binary') {
         if (!Buffer.isBuffer(framePayload) || framePayload.length < 1) {
             device.counters.audioFramesDropped += 1;
             return false;
@@ -4637,9 +5543,184 @@ export function createRemoteHub(options = {}) {
             payload: framePayload,
             byteLength: framePayload.length
         });
-        return true;
-    }
-
+        return true;
+    }
+
+    function readFrameTransportProof(message = {}) {
+        if (message.frameTransportProofId === undefined
+            && message.frameTransportProofVersion === undefined) {
+            return null;
+        }
+        const rawProofId = typeof message.frameTransportProofId === 'string'
+            ? message.frameTransportProofId.trim()
+            : '';
+        const captureGeneration = Number(message.captureGeneration);
+        const monitorIndex = parseExactLiveStreamMonitorIndex(message.monitorIndex);
+        const proof = {
+            proofId: rawProofId,
+            streamId: safeString(message.streamId, 128),
+            commandId: safeString(message.commandId, 128),
+            captureGeneration,
+            monitorIndex
+        };
+        const valid = Number(message.frameTransportProofVersion) === 1
+            && /^[a-f0-9]{32}$/.test(rawProofId)
+            && !!proof.streamId
+            && !!proof.commandId
+            && Number.isSafeInteger(captureGeneration)
+            && captureGeneration > 0
+            && monitorIndex !== null;
+        return {
+            ...proof,
+            valid,
+            error: valid ? '' : 'frame-proof-owner-invalid'
+        };
+    }
+
+    function applyLiveFrameWithTransportProof(
+        device,
+        message,
+        framePayload,
+        transport) {
+        const proof = readFrameTransportProof(message);
+        if (!proof) {
+            return {
+                accepted: applyLiveFrame(device, message, framePayload, transport),
+                proofAccepted: false,
+                proof: null,
+                error: ''
+            };
+        }
+        const frameMode = safeString(message.frameMode || message.mode, 40).toLowerCase();
+        const mimeType = safeString(message.mimeType || message.format, 80).toLowerCase();
+        const chunkType = safeString(message.chunkType, 20).toLowerCase();
+        const proofFrameSeq = Number(message.frameSeq);
+        const proofStreamFrameSeq = message.streamFrameSeq === undefined
+            || message.streamFrameSeq === null
+            || message.streamFrameSeq === ''
+            ? proofFrameSeq
+            : Number(message.streamFrameSeq);
+        const proofOnly = message.frameTransportProofOnly === true;
+        const h264 = inspectAnnexBH264(framePayload);
+        const proofPayloadValid = proof.valid
+            && (transport === 'udp-p2p' || transport === 'relay-binary')
+            && Buffer.isBuffer(framePayload)
+            && framePayload.length > 0
+            && framePayload.length <= MAX_STREAM_BINARY_BYTES
+            && Number.isSafeInteger(proofFrameSeq)
+            && proofFrameSeq > 0
+            && Number.isSafeInteger(proofStreamFrameSeq)
+            && proofStreamFrameSeq > 0
+            && frameMode === 'mode3-h264-hw'
+            && mimeType === 'video/h264'
+            && (message.isKeyFrame === true || chunkType === 'key')
+            && safeString(message.frameTransportActive, 20).toLowerCase() === 'none'
+            && safeString(message.frameTransportState, 20).toLowerCase() === 'probing'
+            && h264.annexB
+            && h264.hasSps
+            && h264.hasPps
+            && h264.hasIdr
+            && h264.nalOrderValid;
+        if (!proofPayloadValid) {
+            device.counters.liveFramesDropped += 1;
+            emitRemoteEvent('RemoteFrameDropped', device, {
+                reason: proof.error || 'frame-proof-h264-invalid',
+                streamId: proof.streamId,
+                commandId: proof.commandId,
+                captureGeneration: proof.captureGeneration,
+                monitorIndex: proof.monitorIndex,
+                transport
+            });
+            return {
+                accepted: false,
+                proofAccepted: false,
+                proof,
+                error: proof.error || 'frame-proof-h264-invalid'
+            };
+        }
+        if (proofOnly) {
+            const streamState = getDeviceLiveStream(device, proof.streamId);
+            // A proof-only frame is an out-of-band path challenge. It must
+            // prove the exact current stream owner and carry a complete
+            // independently decodable H.264 key frame, but it must not race
+            // the presentation lane's latest delta frame. WAN fragmentation
+            // can legitimately deliver this challenge several relay frames
+            // after the same source key was presented.
+            const exactActiveStreamOwner = transport === 'udp-p2p'
+                && streamState?.active === true
+                && safeString(streamState.commandId, 128) === proof.commandId
+                && Number(streamState.captureGeneration || 0) === proof.captureGeneration
+                && parseExactLiveStreamMonitorIndex(streamState.monitorIndex) === proof.monitorIndex;
+            if (exactActiveStreamOwner) {
+                emitRemoteEvent('RemoteFrameTransportProofAccepted', device, {
+                    proofOnly: true,
+                    proofId: proof.proofId,
+                    streamId: proof.streamId,
+                    commandId: proof.commandId,
+                    captureGeneration: proof.captureGeneration,
+                    monitorIndex: proof.monitorIndex,
+                    frameSeq: proofFrameSeq,
+                    streamFrameSeq: proofStreamFrameSeq,
+                    transport
+                });
+            }
+            return {
+                accepted: exactActiveStreamOwner,
+                proofAccepted: exactActiveStreamOwner,
+                proofOnly: true,
+                proof,
+                error: exactActiveStreamOwner
+                    ? ''
+                    : 'frame-proof-active-owner-mismatch'
+            };
+        }
+        const accepted = applyLiveFrame(device, message, framePayload, transport);
+        const frame = device.latestLiveFrame;
+        const exactAcceptedFrame = accepted
+            && frame?.currentGenerationVerified === true
+            && safeString(frame.streamId, 128) === proof.streamId
+            && safeString(frame.commandId, 128) === proof.commandId
+            && Number(frame.captureGeneration) === proof.captureGeneration
+            && parseExactLiveStreamMonitorIndex(frame.monitorIndex) === proof.monitorIndex;
+        if (exactAcceptedFrame) {
+            emitRemoteEvent('RemoteFrameTransportProofAccepted', device, {
+                proofOnly: false,
+                proofId: proof.proofId,
+                streamId: proof.streamId,
+                commandId: proof.commandId,
+                captureGeneration: proof.captureGeneration,
+                monitorIndex: proof.monitorIndex,
+                frameSeq: proofFrameSeq,
+                streamFrameSeq: proofStreamFrameSeq,
+                transport
+            });
+        }
+        return {
+            accepted: exactAcceptedFrame,
+            proofAccepted: exactAcceptedFrame,
+            proof,
+            error: exactAcceptedFrame ? '' : 'frame-proof-current-generation-rejected'
+        };
+    }
+
+    function writeFrameTransportProofResponse(socket, result) {
+        const proof = result?.proof;
+        if (!proof?.proofId) return;
+        const accepted = result.proofAccepted === true;
+        writeJsonLine(socket, {
+            type: accepted
+                ? 'frame.transport.proof-accepted'
+                : 'frame.transport.proof-rejected',
+            protocol: 'livedesk.frame-transport-proof.v1',
+            proofId: proof.proofId,
+            streamId: proof.streamId,
+            commandId: proof.commandId,
+            captureGeneration: proof.captureGeneration,
+            monitorIndex: proof.monitorIndex,
+            ...(accepted ? {} : { error: safeString(result.error || 'frame-proof-rejected', 160) })
+        });
+    }
+
     function handleAgentBinaryFrame(socket, state, header, framePayload) {
         if (!state.authenticated || !state.device) {
             writeJsonLine(socket, { type: 'error', error: 'hello-required' });
@@ -4675,10 +5756,12 @@ export function createRemoteHub(options = {}) {
         }
 
         if (frameKind === 'stream' || frameKind === 'live' || header.type === 'stream.binary') {
-            applyLiveFrame(device, {
+            const result = applyLiveFrameWithTransportProof(device, {
                 ...header,
-                hubIngressDropped: Number(state.binaryQueueDrops || 0)
+                hubIngressDropped: Number(state.binaryQueueDrops || 0),
+                hubIngressCounterEpoch: state.binaryQueueEpoch
             }, framePayload, binaryTransport);
+            writeFrameTransportProofResponse(socket, result);
             return;
         }
 
@@ -4698,7 +5781,7 @@ export function createRemoteHub(options = {}) {
         });
     }
 
-    function handleUdpFrame({ deviceId, sessionId, header, payload } = {}) {
+    function handleUdpFrame({ deviceId, sessionId, header, payload } = {}) {
         const device = devices.get(safeString(deviceId, 160));
         if (!device || !device.connected) {
             return false;
@@ -4711,18 +5794,25 @@ export function createRemoteHub(options = {}) {
             emitRemoteEvent('RemoteFrameDropped', device, { reason: 'udp-frame-mode-not-supported', transport: 'udp-p2p', frameMode });
             return false;
         }
-        device.udp = {
-            ...device.udp,
-            state: 'udp-active',
-            ready: true,
-            lastFrameAt: new Date().toISOString(),
-            framesReceived: Number(device.udp?.framesReceived || 0) + 1
-        };
-        return applyLiveFrame(device, {
-            ...header,
-            transport: 'udp-p2p'
-        }, payload, 'udp-p2p');
-    }
+        const result = applyLiveFrameWithTransportProof(device, {
+            ...header,
+            transport: 'udp-p2p',
+            hubIngressCounterEpoch: sessionId
+        }, payload, 'udp-p2p');
+        if (result.accepted) {
+            device.udp = {
+                ...device.udp,
+                state: result.proof ? 'udp-proof-accepted' : 'udp-active',
+                ready: true,
+                lastFrameAt: new Date().toISOString(),
+                framesReceived: Number(device.udp?.framesReceived || 0)
+                    + (result.proofOnly === true ? 0 : 1)
+            };
+        }
+        return result.proof
+            ? result
+            : result.accepted;
+    }
 
     function dropQueuedAgentBinaryFrame(state) {
         if (!Array.isArray(state.binaryQueue) || state.binaryQueue.length === 0) {
@@ -5051,9 +6141,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(() => {
@@ -5211,9 +6302,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(() => {
@@ -5437,8 +6529,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');
@@ -5490,10 +6583,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');
@@ -7547,6 +8641,10 @@ export function createRemoteHub(options = {}) {
         stopLiveStream,
         pauseLiveCapture,
         resumeLiveCapture,
+        startTransportDiagnostic,
+        getTransportDiagnostic,
+        setTransportDiagnosticPhase,
+        stopTransportDiagnostic,
         startAudioStream,
         stopAudioStream,
         getDeviceLiveFrame,