pi-lean-dimension 0.1.0 → 0.2.1

package/node_modules/pi-lean-portal/__tests__/plugin-loading.test.ts

@@ -11,9 +11,12 @@ import { mkdtempSync, mkdirSync, writeFileSync, rmSync } from "node:fs";
 import { join } from "node:path";
 import { tmpdir } from "node:os";
 
-import { detectPluginType, DEFAULT_BACKENDS_ROOT } from "../core/plugin-config";
-import { PluginRegistry } from "../core/plugin-registry";
-import type { PluginConfig } from "../core/plugin-config";
+import {
+	detectPluginType,
+	DEFAULT_BACKENDS_ROOT,
+} from "../core/plugin-config.js";
+import { PluginRegistry } from "../core/plugin-registry.js";
+import type { PluginConfig } from "../core/plugin-config.js";
 
 // ─── Helpers ─────────────────────────────────────────────────────
 
@@ -54,7 +57,7 @@ describe("detectPluginType", () => {
 		backendsRoot = createTestBackendsRoot({
 			"my-node-plugin": { "index.ts": "export class MyPlugin {}" },
 		});
-		const result = detectPluginType("my-node-plugin", backendsRoot);
+		const result = detectPluginType("my-node-plugin", [backendsRoot]);
 		expect(result.type).toBe("node");
 		expect(result.entryPoint).toBe(
 			join(backendsRoot, "my-node-plugin", "index.ts"),
@@ -65,7 +68,7 @@ describe("detectPluginType", () => {
 		backendsRoot = createTestBackendsRoot({
 			"my-py-plugin": { "bridge.py": "class MyBridge: pass" },
 		});
-		const result = detectPluginType("my-py-plugin", backendsRoot);
+		const result = detectPluginType("my-py-plugin", [backendsRoot]);
 		expect(result.type).toBe("python");
 		expect(result.entryPoint).toBe(
 			join(backendsRoot, "my-py-plugin", "bridge.py"),
@@ -79,7 +82,7 @@ describe("detectPluginType", () => {
 				"bridge.py": "class X: pass",
 			},
 		});
-		expect(() => detectPluginType("ambiguous", backendsRoot)).toThrow(
+		expect(() => detectPluginType("ambiguous", [backendsRoot])).toThrow(
 			/ambiguous/,
 		);
 	});
@@ -88,14 +91,14 @@ describe("detectPluginType", () => {
 		backendsRoot = createTestBackendsRoot({
 			"empty-plugin": { "readme.md": "# Nothing useful" },
 		});
-		expect(() => detectPluginType("empty-plugin", backendsRoot)).toThrow(
+		expect(() => detectPluginType("empty-plugin", [backendsRoot])).toThrow(
 			/no entry point/i,
 		);
 	});
 
 	it("throws for non-existent dir", () => {
 		backendsRoot = createTestBackendsRoot({});
-		expect(() => detectPluginType("nonexistent", backendsRoot)).toThrow(
+		expect(() => detectPluginType("nonexistent", [backendsRoot])).toThrow(
 			/no entry point/i,
 		);
 	});
@@ -106,28 +109,28 @@ describe("detectPluginType", () => {
 describe("detectPluginType — production backends", () => {
 	it("detects the chromium backend as a Node plugin", () => {
 		// This tests the actual backends/chromium/ directory
-		const result = detectPluginType("chromium", DEFAULT_BACKENDS_ROOT);
+		const result = detectPluginType("chromium", [DEFAULT_BACKENDS_ROOT]);
 		expect(result.type).toBe("node");
 		expect(result.entryPoint).toContain("chromium/index.ts");
 	});
 
 	it("detects the firefox backend as a Node plugin", () => {
 		// This tests the actual backends/firefox/ directory
-		const result = detectPluginType("firefox", DEFAULT_BACKENDS_ROOT);
+		const result = detectPluginType("firefox", [DEFAULT_BACKENDS_ROOT]);
 		expect(result.type).toBe("node");
 		expect(result.entryPoint).toContain("firefox/index.ts");
 	});
 
 	it("detects the chromium-py backend as a Python plugin", () => {
 		// This tests the actual backends/chromium-py/ directory
-		const result = detectPluginType("chromium-py", DEFAULT_BACKENDS_ROOT);
+		const result = detectPluginType("chromium-py", [DEFAULT_BACKENDS_ROOT]);
 		expect(result.type).toBe("python");
 		expect(result.entryPoint).toContain("chromium-py/bridge.py");
 	});
 
 	it("detects the firefox-py backend as a Python plugin", () => {
 		// This tests the actual backends/firefox-py/ directory
-		const result = detectPluginType("firefox-py", DEFAULT_BACKENDS_ROOT);
+		const result = detectPluginType("firefox-py", [DEFAULT_BACKENDS_ROOT]);
 		expect(result.type).toBe("python");
 		expect(result.entryPoint).toContain("firefox-py/bridge.py");
 	});
@@ -170,7 +173,7 @@ describe("plugin startup loop integration", () => {
 		const errors: string[] = [];
 		for (const config of configs) {
 			try {
-				detectPluginType(config.dir, backendsRoot);
+				detectPluginType(config.dir, [backendsRoot]);
 			} catch (err) {
 				errors.push(
 					`Plugin '${config.name}' (dir: '${config.dir}'): ${err instanceof Error ? err.message : String(err)}`,
@@ -181,7 +184,6 @@ describe("plugin startup loop integration", () => {
 		expect(errors).toHaveLength(1);
 		expect(errors[0]).toContain("nonexistent");
 		expect(errors[0]).toContain("no entry point");
-		expect(registry.size).toBe(0);
 	});
 
 	it("skips plugins with ambiguous directories and logs error", () => {
@@ -198,7 +200,7 @@ describe("plugin startup loop integration", () => {
 		const errors: string[] = [];
 		for (const config of configs) {
 			try {
-				detectPluginType(config.dir, backendsRoot);
+				detectPluginType(config.dir, [backendsRoot]);
 			} catch (err) {
 				errors.push(
 					`Plugin '${config.name}' (dir: '${config.dir}'): ${err instanceof Error ? err.message : String(err)}`,
@@ -208,7 +210,6 @@ describe("plugin startup loop integration", () => {
 
 		expect(errors).toHaveLength(1);
 		expect(errors[0]).toContain("ambiguous");
-		expect(registry.size).toBe(0);
 	});
 
 	it("correctly classifies multiple plugins of different types", () => {
@@ -223,7 +224,7 @@ describe("plugin startup loop integration", () => {
 
 		const detections = configs.map((config) => ({
 			config,
-			detection: detectPluginType(config.dir, backendsRoot),
+			detection: detectPluginType(config.dir, [backendsRoot]),
 		}));
 
 		expect(detections[0]!.detection.type).toBe("node");
@@ -240,7 +241,7 @@ describe("plugin startup loop integration", () => {
 
 		const detections = configs.map((config) => ({
 			config,
-			detection: detectPluginType(config.dir, backendsRoot),
+			detection: detectPluginType(config.dir, [backendsRoot]),
 		}));
 
 		expect(detections[0]!.detection.type).toBe("python");
@@ -257,3 +258,104 @@ describe("DEFAULT_BACKENDS_ROOT", () => {
 		expect(DEFAULT_BACKENDS_ROOT).toMatch(/^\//);
 	});
 });
+
+// ─── Multi-root discovery (Phase 0b) ─────────────────────────────
+
+describe("detectPluginType — multi-root", () => {
+	let packageRoot: string;
+	let userRoot: string;
+	const createdRoots: string[] = [];
+
+	beforeEach(() => {
+		packageRoot = createTestBackendsRoot({});
+		userRoot = createTestBackendsRoot({});
+		createdRoots.push(packageRoot, userRoot);
+	});
+
+	afterEach(() => {
+		for (const r of createdRoots.splice(0)) {
+			try {
+				cleanupTestBackendsRoot(r);
+			} catch {
+				/* ignore */
+			}
+		}
+	});
+
+	it("resolves a backend found in the user root when absent from the package root", () => {
+		// Place a Python backend only in the user root
+		const dir = join(userRoot, "camoufox-py");
+		mkdirSync(dir, { recursive: true });
+		writeFileSync(join(dir, "bridge.py"), "class X: pass");
+
+		const result = detectPluginType("camoufox-py", [packageRoot, userRoot]);
+		expect(result.type).toBe("python");
+		expect(result.entryPoint).toBe(join(userRoot, "camoufox-py", "bridge.py"));
+	});
+
+	it("package root wins over user root when both contain the same dir name", () => {
+		// 'chromium' in package root (index.ts) AND user root (bridge.py)
+		const pkgDir = join(packageRoot, "shared-name");
+		mkdirSync(pkgDir, { recursive: true });
+		writeFileSync(join(pkgDir, "index.ts"), "export class X {}");
+		const usrDir = join(userRoot, "shared-name");
+		mkdirSync(usrDir, { recursive: true });
+		writeFileSync(join(usrDir, "bridge.py"), "class X: pass");
+
+		const result = detectPluginType("shared-name", [packageRoot, userRoot]);
+		expect(result.type).toBe("node");
+		expect(result.entryPoint).toBe(
+			join(packageRoot, "shared-name", "index.ts"),
+		);
+	});
+
+	it("absolute dir short-circuits the roots list", () => {
+		const absDir = mkdtempSync(join(tmpdir(), "pi-lean-portal-abs-"));
+		createdRoots.push(absDir);
+		writeFileSync(join(absDir, "bridge.py"), "class X: pass");
+
+		// Pass roots that do NOT contain this dir; the absolute path must still win.
+		const result = detectPluginType(absDir, [packageRoot, userRoot]);
+		expect(result.type).toBe("python");
+		expect(result.entryPoint).toBe(join(absDir, "bridge.py"));
+	});
+
+	it("throws an error naming all roots searched when no root has an entry point", () => {
+		expect(() => detectPluginType("missing", [packageRoot, userRoot])).toThrow(
+			/no entry point/i,
+		);
+
+		try {
+			detectPluginType("missing", [packageRoot, userRoot]);
+		} catch (err) {
+			const msg = err instanceof Error ? err.message : String(err);
+			// Both roots are named in the error so users can see where it looked.
+			expect(msg).toContain(packageRoot);
+			expect(msg).toContain(userRoot);
+		}
+	});
+
+	it("per-root ambiguity is still an error even with multiple roots", () => {
+		const dir = join(userRoot, "ambiguous");
+		mkdirSync(dir, { recursive: true });
+		writeFileSync(join(dir, "index.ts"), "export class X {}");
+		writeFileSync(join(dir, "bridge.py"), "class X: pass");
+
+		expect(() =>
+			detectPluginType("ambiguous", [packageRoot, userRoot]),
+		).toThrow(/ambiguous/);
+	});
+
+	it("a later root with the opposite entry type is NOT treated as ambiguity", () => {
+		// package root: index.ts ; user root (same name): bridge.py — first wins, no error.
+		const pkgDir = join(packageRoot, "split");
+		mkdirSync(pkgDir, { recursive: true });
+		writeFileSync(join(pkgDir, "index.ts"), "export class X {}");
+		const usrDir = join(userRoot, "split");
+		mkdirSync(usrDir, { recursive: true });
+		writeFileSync(join(usrDir, "bridge.py"), "class X: pass");
+
+		const result = detectPluginType("split", [packageRoot, userRoot]);
+		expect(result.type).toBe("node");
+	});
+});

package/node_modules/pi-lean-portal/__tests__/plugin-registry.test.ts

@@ -3,8 +3,8 @@
  */
 
 import { describe, it, expect, beforeEach } from "vitest";
-import { PluginRegistry, validatePlugin } from "../core/plugin-registry";
-import { MockPlugin, makeConfig } from "./helpers/mock-plugin";
+import { PluginRegistry, validatePlugin } from "../core/plugin-registry.js";
+import { MockPlugin, makeConfig } from "./helpers/mock-plugin.js";
 
 // ─── validatePlugin ──────────────────────────────────────────────
 
@@ -70,7 +70,6 @@ describe("PluginRegistry.register", () => {
 	it("registers a valid plugin", () => {
 		const plugin = new MockPlugin("chromium");
 		registry.register(plugin, makeConfig({ name: "chromium" }));
-		expect(registry.size).toBe(1);
 	});
 
 	it("throws on duplicate name", () => {
@@ -98,7 +97,6 @@ describe("PluginRegistry.register", () => {
 		const p2 = new MockPlugin("firefox");
 		registry.register(p1, makeConfig({ name: "chromium" }));
 		registry.register(p2, makeConfig({ name: "firefox" }));
-		expect(registry.size).toBe(2);
 	});
 });
 
@@ -181,11 +179,7 @@ describe("PluginRegistry.getOrdered", () => {
 		registry.register(p2, makeConfig({ name: "beta" }));
 		registry.register(p3, makeConfig({ name: "gamma" }));
 		const ordered = registry.getOrdered();
-		expect(ordered.map((e) => e.plugin.name)).toEqual([
-			"alpha",
-			"beta",
-			"gamma",
-		]);
+		expect(ordered.map((p) => p.name)).toEqual(["alpha", "beta", "gamma"]);
 	});
 
 	it("excludes disabled plugins", () => {
@@ -196,17 +190,16 @@ describe("PluginRegistry.getOrdered", () => {
 		registry.register(p2, makeConfig({ name: "beta", enabled: false }));
 		registry.register(p3, makeConfig({ name: "gamma" }));
 		const ordered = registry.getOrdered();
-		expect(ordered.map((e) => e.plugin.name)).toEqual(["alpha", "gamma"]);
+		expect(ordered.map((p) => p.name)).toEqual(["alpha", "gamma"]);
 	});
 
-	it("assigns correct priority levels", () => {
+	it("preserves registration order across enabled plugins", () => {
 		const p1 = new MockPlugin("alpha");
 		const p2 = new MockPlugin("beta");
 		registry.register(p1, makeConfig({ name: "alpha" }));
 		registry.register(p2, makeConfig({ name: "beta" }));
 		const ordered = registry.getOrdered();
-		expect(ordered[0]!.level).toBe(0);
-		expect(ordered[1]!.level).toBe(1);
+		expect(ordered.map((p) => p.name)).toEqual(["alpha", "beta"]);
 	});
 
 	it("returns empty array when no plugins are enabled", () => {
@@ -257,39 +250,6 @@ describe("PluginRegistry.availableAll", () => {
 	});
 });
 
-// ─── PluginRegistry.getHigherStealth ──────────────────────────────
-
-describe("PluginRegistry.getHigherStealth", () => {
-	let registry: PluginRegistry;
-
-	beforeEach(() => {
-		registry = new PluginRegistry();
-	});
-
-	it("returns plugins at higher priority levels", () => {
-		const p1 = new MockPlugin("chromium");
-		const p2 = new MockPlugin("stealth");
-		registry.register(p1, makeConfig({ name: "chromium" }));
-		registry.register(p2, makeConfig({ name: "stealth" }));
-		const higher = registry.getHigherStealth(0);
-		expect(higher.map((e) => e.plugin.name)).toEqual(["stealth"]);
-	});
-
-	it("returns empty array when no higher-priority plugins exist", () => {
-		const p1 = new MockPlugin("chromium");
-		registry.register(p1, makeConfig({ name: "chromium" }));
-		expect(registry.getHigherStealth(0)).toEqual([]);
-	});
-
-	it("excludes disabled plugins from higher priority", () => {
-		const p1 = new MockPlugin("chromium");
-		const p2 = new MockPlugin("stealth");
-		registry.register(p1, makeConfig({ name: "chromium" }));
-		registry.register(p2, makeConfig({ name: "stealth", enabled: false }));
-		expect(registry.getHigherStealth(0)).toEqual([]);
-	});
-});
-
 // ─── PluginRegistry.resolveStrategy ──────────────────────────────
 
 describe("PluginRegistry.resolveStrategy", () => {
@@ -371,32 +331,11 @@ describe("PluginRegistry.clear", () => {
 		const p2 = new MockPlugin("firefox");
 		registry.register(p1, makeConfig({ name: "chromium" }));
 		registry.register(p2, makeConfig({ name: "firefox" }));
-		expect(registry.size).toBe(2);
 		registry.clear();
-		expect(registry.size).toBe(0);
 		expect(registry.available()).toEqual([]);
 	});
 });
 
-// ─── PluginRegistry.getLevel ─────────────────────────────────────
-
-describe("PluginRegistry.getLevel", () => {
-	it("returns the priority level of a registered plugin", () => {
-		const registry = new PluginRegistry();
-		const p1 = new MockPlugin("chromium");
-		const p2 = new MockPlugin("stealth");
-		registry.register(p1, makeConfig({ name: "chromium" }));
-		registry.register(p2, makeConfig({ name: "stealth" }));
-		expect(registry.getLevel("chromium")).toBe(0);
-		expect(registry.getLevel("stealth")).toBe(1);
-	});
-
-	it("returns undefined for unknown plugin", () => {
-		const registry = new PluginRegistry();
-		expect(registry.getLevel("nonexistent")).toBeUndefined();
-	});
-});
-
 // ─── MockPlugin call tracking ────────────────────────────────────
 
 describe("MockPlugin call tracking", () => {

package/node_modules/pi-lean-portal/__tests__/probe-user-backend.test.ts

@@ -0,0 +1,236 @@
+/**
+ * Unit tests for `probeUserBackend` (Sprint 1, AC 1.2).
+ *
+ * Structural — no real browser, no MiniWoB content. Uses a temp
+ * directory as `PI_USER_BACKENDS_DIR` so nothing is written to the
+ * real `~/.pi/agent/pi-lean-portal/user-backends/`. The "venv runs"
+ * case uses a tiny `#!/bin/sh\nexit 0` stub executable so the test is
+ * self-contained and does not depend on python3 being installed at a
+ * known path; the "non-runnable" case uses an exit-1 stub.
+ *
+ * @module
+ */
+
+import { afterEach, beforeEach, describe, expect, it } from "vitest";
+import {
+	chmodSync,
+	existsSync,
+	mkdirSync,
+	mkdtempSync,
+	rmSync,
+	writeFileSync,
+} from "node:fs";
+import { homedir, tmpdir } from "node:os";
+import { join } from "node:path";
+
+import {
+	probeUserBackend,
+	userBackendsDir,
+} from "./helpers/probe-user-backend.js";
+
+// ─── Helpers ──────────────────────────────────────────────────────
+
+/**
+ * Create a stub "python3" executable at `<dir>/.venv/bin/python3` that
+ * exits with `exitCode`. Mimics a runnable (exit 0) or broken (exit 1)
+ * venv interpreter for the probe's `spawnSync(…, ["--version"])` check.
+ */
+function makeStubPython(dir: string, exitCode: number): string {
+	const binDir = join(dir, ".venv", "bin");
+	mkdirSync(binDir, { recursive: true });
+	const pyPath = join(binDir, "python3");
+	writeFileSync(pyPath, `#!/bin/sh\nexit ${exitCode}\n`);
+	chmodSync(pyPath, 0o755);
+	return pyPath;
+}
+
+/** Write a stub `bridge.py` at `<dir>/bridge.py`. */
+function makeStubBridge(dir: string): string {
+	mkdirSync(dir, { recursive: true });
+	const bridgePath = join(dir, "bridge.py");
+	writeFileSync(bridgePath, "# stub bridge\n");
+	return bridgePath;
+}
+
+// ─── Test env snapshot / restore ──────────────────────────────────
+
+let tempRoot: string;
+let savedDir: string | undefined;
+/** Per-name `PI_USER_BACKEND_<UPPERNAME>_PYTHON` keys set during a test. */
+let touchedPythonKeys: string[] = [];
+/** Saved values of per-name python env overrides, for afterEach restore. */
+const savedEnv = new Map<string, string | undefined>();
+
+function setPythonOverride(name: string, value: string): void {
+	const key = `PI_USER_BACKEND_${name.toUpperCase()}_PYTHON`;
+	if (!savedEnv.has(key)) savedEnv.set(key, process.env[key]);
+	touchedPythonKeys.push(key);
+	process.env[key] = value;
+}
+
+beforeEach(() => {
+	tempRoot = mkdtempSync(join(tmpdir(), "probe-user-backend-"));
+	savedDir = process.env.PI_USER_BACKENDS_DIR;
+	savedEnv.clear();
+	touchedPythonKeys = [];
+	process.env.PI_USER_BACKENDS_DIR = tempRoot;
+});
+
+afterEach(() => {
+	rmSync(tempRoot, { recursive: true, force: true });
+	// Restore PI_USER_BACKENDS_DIR.
+	if (savedDir === undefined)
+		Reflect.deleteProperty(process.env, "PI_USER_BACKENDS_DIR");
+	else process.env.PI_USER_BACKENDS_DIR = savedDir;
+	// Restore (or delete) any per-name python overrides set during the test.
+	for (const key of touchedPythonKeys) {
+		const saved = savedEnv.get(key);
+		if (saved === undefined) Reflect.deleteProperty(process.env, key);
+		else process.env[key] = saved;
+	}
+	touchedPythonKeys = [];
+});
+
+// ─── userBackendsDir ──────────────────────────────────────────────
+
+describe("userBackendsDir", () => {
+	it("honors PI_USER_BACKENDS_DIR when set", () => {
+		expect(userBackendsDir()).toBe(tempRoot);
+	});
+
+	it("falls back to ~/.pi/agent/pi-lean-portal/user-backends when unset", () => {
+		Reflect.deleteProperty(process.env, "PI_USER_BACKENDS_DIR");
+		const expected = join(
+			homedir(),
+			".pi",
+			"agent",
+			"pi-lean-portal",
+			"user-backends",
+		);
+		expect(userBackendsDir()).toBe(expected);
+	});
+
+	it("treats an empty PI_USER_BACKENDS_DIR as unset", () => {
+		process.env.PI_USER_BACKENDS_DIR = "   ";
+		const expected = join(
+			homedir(),
+			".pi",
+			"agent",
+			"pi-lean-portal",
+			"user-backends",
+		);
+		expect(userBackendsDir()).toBe(expected);
+	});
+});
+
+// ─── probeUserBackend ─────────────────────────────────────────────
+
+describe("probeUserBackend", () => {
+	it("returns available=true with correct paths when bridge + venv present", () => {
+		const name = "camoufox-py";
+		const backendDir = join(tempRoot, name);
+		const bridge = makeStubBridge(backendDir);
+		const py = makeStubPython(backendDir, 0);
+
+		const result = probeUserBackend(name);
+
+		expect(result.available).toBe(true);
+		expect(result.reason).toBeUndefined();
+		expect(result.bridgePath).toBe(bridge);
+		expect(result.venvPython).toBe(py);
+	});
+
+	it("returns available=false with a bridge-mentioning reason when bridge.py is missing", () => {
+		const name = "camoufox-py";
+		// venv present but no bridge.py
+		const py = makeStubPython(join(tempRoot, name), 0);
+		const expectedBridge = join(tempRoot, name, "bridge.py");
+
+		const result = probeUserBackend(name);
+
+		expect(result.available).toBe(false);
+		expect(result.reason).toMatch(/bridge/i);
+		expect(result.reason).toContain(expectedBridge);
+		expect(result.bridgePath).toBe(expectedBridge);
+		expect(result.venvPython).toBe(py);
+	});
+
+	it("returns available=false with a venv-mentioning reason when venv python is missing", () => {
+		const name = "stealth-py";
+		const backendDir = join(tempRoot, name);
+		makeStubBridge(backendDir);
+		const expectedPy = join(backendDir, ".venv", "bin", "python3");
+
+		const result = probeUserBackend(name);
+
+		expect(result.available).toBe(false);
+		expect(result.reason).toMatch(/venv|python/i);
+		expect(result.reason).toContain(expectedPy);
+		expect(result.venvPython).toBe(expectedPy);
+	});
+
+	it("returns available=false with a venv-mentioning reason when venv python exists but does not run", () => {
+		const name = "stealth-py";
+		const backendDir = join(tempRoot, name);
+		makeStubBridge(backendDir);
+		const py = makeStubPython(backendDir, 1); // exits non-zero
+
+		const result = probeUserBackend(name);
+
+		expect(result.available).toBe(false);
+		expect(result.reason).toMatch(/venv|python/i);
+		expect(result.reason).toContain(py);
+		expect(result.venvPython).toBe(py);
+	});
+
+	it("respects PI_USER_BACKEND_<UPPERNAME>_PYTHON env override for venvPython", () => {
+		const name = "camoufox-py";
+		const backendDir = join(tempRoot, name);
+		makeStubBridge(backendDir);
+		// Do NOT create the default .venv; instead point the env override at a
+		// stub python that lives outside the default venv path (but still under
+		// tempRoot so afterEach cleans it up).
+		const overrideDir = join(tempRoot, "override-venv");
+		const overridePy = makeStubPython(overrideDir, 0);
+		setPythonOverride(name, overridePy);
+
+		const result = probeUserBackend(name);
+
+		expect(result.available).toBe(true);
+		expect(result.venvPython).toBe(overridePy);
+		expect(existsSync(join(backendDir, ".venv", "bin", "python3"))).toBe(false);
+	});
+
+	it("respects opts.bridgePath absolute override for bridgePath", () => {
+		const name = "camoufox-py";
+		// Create a bridge.py at an arbitrary absolute location outside the
+		// default user-backends/<name>/ tree (but still under tempRoot so
+		// afterEach cleans it up).
+		const externalDir = join(tempRoot, "override-bridge");
+		const externalBridge = makeStubBridge(externalDir);
+		// Also provide a working venv under the default path so the only thing
+		// being overridden is the bridge location.
+		makeStubPython(join(tempRoot, name), 0);
+
+		const result = probeUserBackend(name, { bridgePath: externalBridge });
+
+		expect(result.available).toBe(true);
+		expect(result.bridgePath).toBe(externalBridge);
+		// The default bridge path is NOT used.
+		expect(result.bridgePath).not.toBe(join(tempRoot, name, "bridge.py"));
+	});
+
+	it("ignores a non-absolute opts.bridgePath and falls back to default resolution", () => {
+		const name = "camoufox-py";
+		const backendDir = join(tempRoot, name);
+		const bridge = makeStubBridge(backendDir);
+		makeStubPython(backendDir, 0);
+
+		// A relative bridgePath must not short-circuit (mirrors detectPluginType,
+		// which only short-circuits on isAbsolute(dir)).
+		const result = probeUserBackend(name, { bridgePath: "relative/bridge.py" });
+
+		expect(result.available).toBe(true);
+		expect(result.bridgePath).toBe(bridge);
+	});
+});