The __dune_env function modifies the PATH with the aim of making it so that when you run dune in your terminal, that refers to the dune from the dune binary distro. After modifying the PATH to this effect, the function should check whether it had the desired effect. If not, we could consider printing a warning with a message instructing users how to fix their PATH.
The reason why __dune_env sometimes doesn't give the binary distro's instance of dune the highest precedence is that it currently doesn't modify PATH if dune's bin directory is already (anywhere) in PATH. It does this to avoid rearranging PATH in situations where dune shares a bin directory with other programs. However this means that if __dune_env is called in an environment where an opam switch is before dune's install location in PATH, __dune_env will not reorder the PATH to give precedence to the dune executable from the dune binary distro.