Java client: let the jar's packaged binary win over a `PATH` install, or warn when they differ

[adrianrobinsondev]

Not a bug report — the current behavior is documented and deliberate. This is a request to
reconsider it for the Maven-consumer case, or to make the mismatch visible.

Current behavior

BinaryResolver states its order in the class doc, and implements exactly that:

/**
 * Finds or extracts the vibium binary.
 *
 * Resolution order:
 * 1. VIBIUM_BIN_PATH environment variable
 * 2. PATH lookup
 * 3. Extract from JAR resources
 */

So a project that pins com.vibium:vibium:X in its build gets client X driving whichever
binary happens to be on PATH — usually an npm install on a different upgrade cycle. The jar
ships binaries for five platforms and they are consulted last.

Why this is awkward for a Maven consumer

The dependency version is the only thing under the build's control, and it is the one thing
that does not determine which binary runs. In our case we built the browser-clouds branch,
published it locally as 26.5.31-browser-clouds, pointed the pom at it, and every run kept
using /usr/bin/vibium from npm — with no indication anything had been overridden.

The resulting failures do not point at a version mismatch:

• branch client + released binary → Error: unknown flag: --connect-caps
• released binary asked to connect to an http:// Selenium Grid endpoint →
  malformed ws or wss URL, which reads as a transport fault rather than a missing feature

For a test suite this is the bad direction to fail in: the ambiguity costs more than a hard
error would.

What we ended up doing

Extracting natives/<platform> from the jar ourselves and passing the result as
StartOptions.executablePath(...), so client and binary are guaranteed to be one build. It
works, but it reimplements part of BinaryResolver in every consuming project.

Request — any one of these would resolve it

1. When the client was resolved from a jar that carries natives/, prefer that binary, keeping
   VIBIUM_BIN_PATH as the explicit override.
2. Keep the order, but log a warning when the PATH binary's version differs from the jar's.
   (This needs the version resource from the sibling issue about vibium-version.txt.)
3. Expose it as API — e.g. StartOptions.usePackagedBinary() — so consumers who want the
   pinned binary can ask for it without reimplementing extraction.

Environment

• com.vibium:vibium:26.5.31 (Maven Central) and a local build of browser-clouds
• Linux x86_64 (RHEL 9), Java 25.0.2, Maven Surefire
• npm vibium@26.5.31 installed globally at /usr/bin/vibium