@blackbelt-technology/pi-agent-dashboard 0.2.9 → 0.4.0

package/packages/shared/src/__tests__/tool-registry-registry.test.ts

@@ -0,0 +1,343 @@
+/**
+ * Tests for ToolRegistry (packages/shared/src/tool-registry/registry.ts).
+ *
+ * Covered scenarios (from `specs/tool-registry/spec.md`):
+ *   - Resolve a registered binary
+ *   - Resolve an unregistered name throws UnknownToolError
+ *   - Cached Resolution is referentially equal on second resolve()
+ *   - rescan(name) invalidates one; rescan() invalidates all
+ *   - First strategy wins; subsequent strategies not executed
+ *   - Failing strategies recorded in tried[] and iteration continues
+ *   - All-fail produces ok:false with full tried[] trail
+ *   - resolveModule: caches loaded module; throws ModuleResolutionError on fail
+ *   - setOverride / clearOverride invalidate cached Resolution
+ */
+import { describe, it, expect } from "vitest";
+import {
+  ToolRegistry,
+  UnknownToolError,
+  ModuleResolutionError,
+  type Strategy,
+  type ToolDefinition,
+} from "../tool-registry/index.js";
+import { OverridesStore } from "../tool-registry/overrides.js";
+import os from "node:os";
+import path from "node:path";
+import fs from "node:fs";
+
+// ── Test helpers ────────────────────────────────────────────────────────────
+
+/** Make a strategy that always returns the given path. */
+function fixedOk(name: string, p: string): Strategy {
+  return { name, run: () => ({ ok: true, path: p }) };
+}
+
+/** Make a strategy that records its invocation for "not executed" assertions. */
+function spyOk(name: string, p: string, tag: { called: boolean }): Strategy {
+  return {
+    name,
+    run: () => {
+      tag.called = true;
+      return { ok: true, path: p };
+    },
+  };
+}
+
+/** Make a strategy that always fails with the given reason. */
+function fail(name: string, reason: string): Strategy {
+  return { name, run: () => ({ ok: false, reason }) };
+}
+
+/** In-memory OverridesStore backed by a tmp file (for set/clear flow). */
+function tmpOverridesStore(): OverridesStore {
+  const fp = path.join(
+    os.tmpdir(),
+    `tool-overrides-test-${process.pid}-${Date.now()}-${Math.random().toString(36).slice(2)}.json`,
+  );
+  return new OverridesStore({ filePath: fp, warn: () => {} });
+}
+
+function binaryDef(name: string, strategies: Strategy[]): ToolDefinition {
+  return { name, kind: "binary", strategies };
+}
+
+function moduleDef(name: string, strategies: Strategy[]): ToolDefinition {
+  return { name, kind: "module", strategies };
+}
+
+// ── Tests ───────────────────────────────────────────────────────────────────
+
+describe("ToolRegistry.resolve", () => {
+  it("returns a Resolution object for a registered binary", () => {
+    const r = new ToolRegistry({ overrides: tmpOverridesStore() });
+    r.register(binaryDef("pi", [fixedOk("where", "/usr/local/bin/pi")]));
+
+    const res = r.resolve("pi");
+    expect(res.name).toBe("pi");
+    expect(res.ok).toBe(true);
+    expect(res.path).toBe("/usr/local/bin/pi");
+    expect(res.tried).toEqual([{ strategy: "where", result: "ok" }]);
+    expect(typeof res.resolvedAt).toBe("number");
+  });
+
+  it("throws UnknownToolError for an unregistered name", () => {
+    const r = new ToolRegistry({ overrides: tmpOverridesStore() });
+    expect(() => r.resolve("nope")).toThrowError(UnknownToolError);
+    try { r.resolve("nope"); } catch (e) {
+      expect((e as UnknownToolError).tool).toBe("nope");
+    }
+  });
+
+  it("returns the same cached Resolution on a second call (referentially equal)", () => {
+    const r = new ToolRegistry({ overrides: tmpOverridesStore() });
+    r.register(binaryDef("pi", [fixedOk("where", "/usr/bin/pi")]));
+
+    const a = r.resolve("pi");
+    const b = r.resolve("pi");
+    expect(a).toBe(b);
+  });
+});
+
+describe("ToolRegistry strategy chain", () => {
+  it("first-successful-strategy wins and short-circuits the chain", () => {
+    const second = { called: false };
+    const r = new ToolRegistry({ overrides: tmpOverridesStore() });
+    r.register(
+      binaryDef("pi", [
+        fixedOk("managed", "/managed/pi"),
+        spyOk("where", "/usr/bin/pi", second),
+      ]),
+    );
+
+    const res = r.resolve("pi");
+    expect(res.ok).toBe(true);
+    expect(res.path).toBe("/managed/pi");
+    expect(res.source).toBe("managed");
+    expect(res.tried).toEqual([{ strategy: "managed", result: "ok" }]);
+    expect(second.called).toBe(false);
+  });
+
+  it("records failing strategies in tried[] and continues", () => {
+    const r = new ToolRegistry({ overrides: tmpOverridesStore() });
+    r.register(
+      binaryDef("pi", [
+        fail("override", "no override set"),
+        fail("managed", "missing: /bad/path"),
+        fixedOk("where", "/usr/bin/pi"),
+      ]),
+    );
+
+    const res = r.resolve("pi");
+    expect(res.ok).toBe(true);
+    expect(res.source).toBe("system");
+    expect(res.tried).toEqual([
+      { strategy: "override", result: "no override set" },
+      { strategy: "managed", result: "missing: /bad/path" },
+      { strategy: "where", result: "ok" },
+    ]);
+  });
+
+  it("produces ok:false with full trail when every strategy fails", () => {
+    const r = new ToolRegistry({ overrides: tmpOverridesStore() });
+    r.register(
+      binaryDef("pi", [fail("a", "reason a"), fail("b", "reason b")]),
+    );
+
+    const res = r.resolve("pi");
+    expect(res.ok).toBe(false);
+    expect(res.path).toBeNull();
+    expect(res.source).toBeNull();
+    expect(res.tried).toEqual([
+      { strategy: "a", result: "reason a" },
+      { strategy: "b", result: "reason b" },
+    ]);
+  });
+
+  it("validate() demotes strategy to failure with 'invalid: <reason>'", () => {
+    const r = new ToolRegistry({ overrides: tmpOverridesStore() });
+    r.register({
+      ...binaryDef("pi", [fixedOk("override", "/bogus"), fixedOk("where", "/usr/bin/pi")]),
+      validate: (p) =>
+        p === "/bogus" ? { ok: false, reason: "not a file" } : { ok: true },
+    });
+
+    const res = r.resolve("pi");
+    expect(res.ok).toBe(true);
+    expect(res.path).toBe("/usr/bin/pi");
+    expect(res.tried[0]).toEqual({ strategy: "override", result: "invalid: not a file" });
+    expect(res.tried[1]).toEqual({ strategy: "where", result: "ok" });
+  });
+});
+
+describe("ToolRegistry.rescan", () => {
+  it("rescan(name) clears just that tool's cache", () => {
+    let callCount = 0;
+    const r = new ToolRegistry({ overrides: tmpOverridesStore() });
+    r.register(
+      binaryDef("pi", [
+        {
+          name: "where",
+          run: () => ({ ok: true, path: `/usr/bin/pi${++callCount}` }),
+        },
+      ]),
+    );
+
+    const first = r.resolve("pi");
+    expect(first.path).toBe("/usr/bin/pi1");
+
+    r.rescan("pi");
+    const second = r.resolve("pi");
+    expect(second.path).toBe("/usr/bin/pi2");
+    expect(second).not.toBe(first);
+  });
+
+  it("rescan() without arg clears everything", () => {
+    let a = 0, b = 0;
+    const r = new ToolRegistry({ overrides: tmpOverridesStore() });
+    r.register(binaryDef("pi", [{ name: "where", run: () => ({ ok: true, path: `/pi${++a}` }) }]));
+    r.register(binaryDef("git", [{ name: "where", run: () => ({ ok: true, path: `/git${++b}` }) }]));
+
+    r.resolve("pi"); r.resolve("git");
+    r.rescan();
+    expect(r.resolve("pi").path).toBe("/pi2");
+    expect(r.resolve("git").path).toBe("/git2");
+  });
+});
+
+describe("ToolRegistry.resolveModule", () => {
+  it("caches the loaded module and returns the same reference on second call", async () => {
+    const fakeModule = { DefaultPackageManager: () => "dpm" };
+    let importCalls = 0;
+    const r = new ToolRegistry({
+      overrides: tmpOverridesStore(),
+      importModule: async () => {
+        importCalls++;
+        return fakeModule;
+      },
+    });
+    r.register(moduleDef("pi-coding-agent", [fixedOk("managed", "/managed/pi/dist/index.js")]));
+
+    const a = await r.resolveModule("pi-coding-agent");
+    const b = await r.resolveModule("pi-coding-agent");
+    expect(a.module).toBe(fakeModule);
+    expect(b.module).toBe(fakeModule);
+    expect(importCalls).toBe(1);
+  });
+
+  it("throws ModuleResolutionError with trail when every strategy fails", async () => {
+    const r = new ToolRegistry({
+      overrides: tmpOverridesStore(),
+      importModule: async () => { throw new Error("should not import"); },
+    });
+    r.register(moduleDef("pi-coding-agent", [fail("a", "nope"), fail("b", "also nope")]));
+
+    await expect(r.resolveModule("pi-coding-agent")).rejects.toBeInstanceOf(ModuleResolutionError);
+    try {
+      await r.resolveModule("pi-coding-agent");
+    } catch (e) {
+      const err = e as ModuleResolutionError;
+      expect(err.resolution.tried).toEqual([
+        { strategy: "a", result: "nope" },
+        { strategy: "b", result: "also nope" },
+      ]);
+      expect(err.message).toContain("a: nope");
+      expect(err.message).toContain("b: also nope");
+    }
+  });
+
+  it("refuses to resolve a non-module tool", async () => {
+    const r = new ToolRegistry({ overrides: tmpOverridesStore() });
+    r.register(binaryDef("pi", [fixedOk("where", "/usr/bin/pi")]));
+    await expect(r.resolveModule("pi")).rejects.toThrow(/not kind: "module"/);
+  });
+
+  it("rescan(name) drops the cached module so the next call re-imports", async () => {
+    let importCalls = 0;
+    const r = new ToolRegistry({
+      overrides: tmpOverridesStore(),
+      importModule: async () => ({ n: ++importCalls }),
+    });
+    r.register(moduleDef("pi-coding-agent", [fixedOk("managed", "/x/dist/index.js")]));
+
+    const a = await r.resolveModule("pi-coding-agent");
+    r.rescan("pi-coding-agent");
+    const b = await r.resolveModule("pi-coding-agent");
+    expect((a.module as { n: number }).n).toBe(1);
+    expect((b.module as { n: number }).n).toBe(2);
+  });
+});
+
+describe("ToolRegistry overrides", () => {
+  it("setOverride invalidates cache and the next resolve() picks override source", () => {
+    const store = tmpOverridesStore();
+    const r = new ToolRegistry({ overrides: store });
+    r.register(
+      binaryDef("pi", [
+        {
+          name: "override",
+          run: (ctx) => ctx.overrides["pi"]
+            ? { ok: true, path: ctx.overrides["pi"] }
+            : { ok: false, reason: "no override set" },
+        },
+        fixedOk("where", "/usr/bin/pi"),
+      ]),
+    );
+
+    expect(r.resolve("pi").path).toBe("/usr/bin/pi");
+    r.setOverride("pi", "/custom/pi");
+    const next = r.resolve("pi");
+    expect(next.path).toBe("/custom/pi");
+    expect(next.source).toBe("override");
+  });
+
+  it("clearOverride removes the entry and falls back to next strategy", () => {
+    const store = tmpOverridesStore();
+    store.set("pi", "/custom/pi");
+    const r = new ToolRegistry({ overrides: store });
+    r.register(
+      binaryDef("pi", [
+        {
+          name: "override",
+          run: (ctx) => ctx.overrides["pi"]
+            ? { ok: true, path: ctx.overrides["pi"] }
+            : { ok: false, reason: "no override set" },
+        },
+        fixedOk("where", "/usr/bin/pi"),
+      ]),
+    );
+
+    expect(r.resolve("pi").path).toBe("/custom/pi");
+    r.clearOverride("pi");
+    expect(r.resolve("pi").path).toBe("/usr/bin/pi");
+  });
+
+  it("setOverride throws UnknownToolError for unregistered names", () => {
+    const r = new ToolRegistry({ overrides: tmpOverridesStore() });
+    expect(() => r.setOverride("ghost", "/x")).toThrow(UnknownToolError);
+  });
+});
+
+describe("ToolRegistry.list", () => {
+  it("returns one Resolution per registered tool", () => {
+    const r = new ToolRegistry({ overrides: tmpOverridesStore() });
+    r.register(binaryDef("pi", [fixedOk("where", "/pi")]));
+    r.register(binaryDef("git", [fail("where", "not found")]));
+
+    const all = r.list();
+    expect(all.map((x) => x.name).sort()).toEqual(["git", "pi"]);
+    expect(all.find((x) => x.name === "pi")!.ok).toBe(true);
+    expect(all.find((x) => x.name === "git")!.ok).toBe(false);
+  });
+});
+
+// Clean up any stray tmp files the tmpOverridesStore helper might leave.
+afterAll();
+function afterAll() {
+  try {
+    for (const f of fs.readdirSync(os.tmpdir())) {
+      if (f.startsWith("tool-overrides-test-")) {
+        try { fs.unlinkSync(path.join(os.tmpdir(), f)); } catch {}
+      }
+    }
+  } catch {}
+}

package/packages/shared/src/bootstrap-install.ts

@@ -0,0 +1,212 @@
+/**
+ * Shared bootstrap installer — single entry point for installing pi,
+ * openspec, tsx, and recommended packages into the managed directory
+ * (~/.pi-dashboard/). Callable from any entry point: Electron wizard,
+ * `pi-dashboard` CLI first-run, `pi-dashboard upgrade-pi` subcommand,
+ * and the `POST /api/bootstrap/upgrade-pi` REST handler.
+ *
+ * This module is deliberately free of Electron-specific concerns
+ * (bundled-node, offline-bundle cacache, resourcesPath). Those remain
+ * in `packages/electron/src/lib/dependency-installer.ts` which now
+ * delegates its "install from npm registry" step to this function.
+ *
+ * See change: unified-bootstrap-install.
+ */
+import { spawn as cpSpawn } from "./platform/exec.js";
+import { existsSync, mkdirSync, writeFileSync } from "node:fs";
+import path from "node:path";
+import { getManagedDir } from "./managed-paths.js";
+import { getDefaultRegistry, type ToolRegistry } from "./tool-registry/index.js";
+
+/**
+ * Per-package progress tick. Mirrors the Electron `InstallProgress`
+ * shape so existing wizard UI code needs no changes.
+ */
+export interface InstallProgress {
+  step: string;
+  status: "pending" | "running" | "done" | "error";
+  error?: string;
+  /** Last line of npm output (for streaming progress). */
+  output?: string;
+}
+
+export type ProgressCallback = (progress: InstallProgress) => void;
+
+export interface BootstrapInstallOptions {
+  /** Packages to install via `npm install <pkg>` (registry fetch). */
+  packages: string[];
+  /** Root of the managed install. Defaults to `getManagedDir()`. */
+  managedDir?: string;
+  /** Called on every progress tick (pending/running/done/error). */
+  progress?: ProgressCallback;
+  /**
+   * Optional override of the npm invocation. By default the function
+   * resolves the `npm` tool via `ToolRegistry.resolve("npm")` and
+   * falls back to the plain `npm` / `npm.cmd` binary on PATH. When
+   * Electron wants to steer the install to bundled Node + npm-cli.js,
+   * it passes the full argv prefix (e.g. `["<path>/node", "<path>/npm-cli.js"]`).
+   */
+  npmArgv?: string[];
+  /**
+   * Optional environment overrides merged into the child process env.
+   * Electron uses this to put bundled Node on PATH for postinstall
+   * scripts.
+   */
+  env?: NodeJS.ProcessEnv;
+  /**
+   * Inject a tool registry (tests). Defaults to `getDefaultRegistry()`.
+   */
+  registry?: ToolRegistry;
+}
+
+export interface BootstrapInstallSuccess {
+  ok: true;
+  installed: string[];
+  managedDir: string;
+}
+
+export interface BootstrapInstallFailure {
+  ok: false;
+  error: string;
+  installed: string[];
+  managedDir: string;
+}
+
+export type BootstrapInstallResult = BootstrapInstallSuccess | BootstrapInstallFailure;
+
+/** Ensure the managed directory exists with a package.json. */
+export function ensureManagedDir(managedDir: string): void {
+  mkdirSync(managedDir, { recursive: true });
+  const pkgPath = path.join(managedDir, "package.json");
+  if (!existsSync(pkgPath)) {
+    writeFileSync(
+      pkgPath,
+      JSON.stringify({ name: "pi-dashboard-managed", private: true, type: "module" }, null, 2),
+    );
+  }
+}
+
+/**
+ * Resolve the npm invocation used for bootstrap installs.
+ *
+ * Order:
+ *   1. Explicit `npmArgv` override (Electron bundled-node case).
+ *   2. `ToolRegistry.resolve("npm")`.
+ *   3. Plain `npm` (Unix) or `npm.cmd` (Windows) on PATH.
+ *
+ * Returns the argv list that will have `install <packages...>` appended.
+ */
+export function resolveNpmArgv(
+  opts: Pick<BootstrapInstallOptions, "npmArgv" | "registry">,
+): string[] {
+  if (opts.npmArgv && opts.npmArgv.length > 0) return [...opts.npmArgv];
+
+  const registry = opts.registry ?? getDefaultRegistry();
+  if (registry.has("npm")) {
+    const res = registry.resolve("npm");
+    if (res.ok && res.path) return [res.path];
+  }
+
+  // Last resort: rely on PATH. On Windows the .cmd shim is required
+  // because spawn doesn't auto-append extensions.
+  const npmBin = process.platform === "win32" ? "npm.cmd" : "npm"; // platform-branch-ok
+  return [npmBin];
+}
+
+/** Internal: spawn npm with a given argv + packages; stream progress. */
+function runNpmOnce(
+  argvBase: string[],
+  packages: string[],
+  cwd: string,
+  env: NodeJS.ProcessEnv,
+  onOutput?: (line: string) => void,
+): Promise<void> {
+  return new Promise((resolve, reject) => {
+    const [cmd, ...baseArgs] = argvBase;
+    if (!cmd) {
+      reject(new Error("resolveNpmArgv returned an empty argv"));
+      return;
+    }
+    const args = [...baseArgs, "install", ...packages];
+
+    const child = cpSpawn(cmd, args, {
+      cwd,
+      env,
+      stdio: ["ignore", "pipe", "pipe"],
+      timeout: 300_000,
+    });
+
+    let tail = "";
+
+    const handleData = (data: Buffer): void => {
+      const text = data.toString();
+      tail += text;
+      if (tail.length > 4096) tail = tail.slice(-4096);
+      const lines = text.split("\n").filter((l) => l.trim());
+      const last = lines[lines.length - 1];
+      if (last && onOutput) onOutput(last.trim().substring(0, 120));
+    };
+
+    child.stdout?.on("data", handleData);
+    child.stderr?.on("data", handleData);
+
+    child.on("error", (err) => reject(new Error(err.message)));
+    child.on("close", (code) => {
+      if (code !== 0) {
+        reject(new Error(tail.slice(-500) || `npm install exited with code ${code}`));
+      } else {
+        resolve();
+      }
+    });
+  });
+}
+
+/**
+ * Install the given packages into the managed directory.
+ *
+ * Per-package progress is reported via `progress`. Installation is
+ * sequential (not concurrent) so a failure stops the chain — matching
+ * the behavior of the Electron wizard today. The return value reports
+ * which packages completed successfully before any failure.
+ */
+export async function bootstrapInstall(
+  opts: BootstrapInstallOptions,
+): Promise<BootstrapInstallResult> {
+  const managedDir = opts.managedDir ?? getManagedDir();
+  ensureManagedDir(managedDir);
+
+  const argvBase = resolveNpmArgv(opts);
+  const env = { ...process.env, ...(opts.env ?? {}) };
+
+  const installed: string[] = [];
+  for (const pkg of opts.packages) {
+    const step = pkg.split("/").pop() || pkg;
+    opts.progress?.({ step, status: "running" });
+    try {
+      await runNpmOnce(argvBase, [pkg], managedDir, env, (output) => {
+        opts.progress?.({ step, status: "running", output });
+      });
+      opts.progress?.({ step, status: "done" });
+      installed.push(pkg);
+    } catch (err) {
+      const message = err instanceof Error ? err.message : String(err);
+      opts.progress?.({ step, status: "error", error: message });
+      return { ok: false, error: message, installed, managedDir };
+    }
+  }
+
+  return { ok: true, installed, managedDir };
+}
+
+/**
+ * Convenience wrapper: install pi, openspec, tsx into the default
+ * managed directory. Used by the CLI degraded-mode first-run path.
+ */
+export async function bootstrapInstallDefaults(
+  progress?: ProgressCallback,
+): Promise<BootstrapInstallResult> {
+  return bootstrapInstall({
+    packages: ["@mariozechner/pi-coding-agent", "@fission-ai/openspec", "tsx"],
+    progress,
+  });
+}

package/packages/shared/src/bridge-register.ts

@@ -10,29 +10,92 @@
 import fs from "node:fs";
 import path from "node:path";
 import os from "node:os";
+import { createRequire } from "node:module";
 
 /**
- * Find the bundled extension directory relative to a base directory.
- * Looks for `packages/extension/` (monorepo layout) under baseDir.
- *
- * Returns null if:
- * - Directory not found
- * - No package.json in the directory
- * - Path is under /tmp/.mount_* (unstable AppImage mount)
+ * Check that a candidate path is a valid, stable extension directory.
+ * Returns true when the directory exists, contains a package.json, and
+ * is NOT under /tmp/.mount_* (unstable AppImage mount).
  */
-export function findBundledExtension(baseDir: string): string | null {
-  const candidate = path.resolve(baseDir, "packages", "extension");
-  if (!fs.existsSync(candidate) || !fs.existsSync(path.join(candidate, "package.json"))) {
-    return null;
+function isValidExtensionPath(candidate: string): boolean {
+  if (!fs.existsSync(candidate)) return false;
+  if (!fs.existsSync(path.join(candidate, "package.json"))) return false;
+  if (candidate.includes("/tmp/.mount_")) {
+    console.warn(
+      "[dashboard] AppImage detected — extension path is temporary, skipping registration:",
+      candidate,
+    );
+    return false;
   }
+  return true;
+}
 
-  // Reject unstable AppImage temp mount paths
-  if (candidate.includes("/tmp/.mount_")) {
-    console.warn("[dashboard] AppImage detected — extension path is temporary, skipping registration:", candidate);
+/**
+ * Optional dependency injection for `findBundledExtension`. Tests pass
+ * `{ resolvePackage: () => null }` to disable the node-resolver fallback.
+ */
+export interface FindExtensionDeps {
+  /**
+   * Resolve `@blackbelt-technology/pi-dashboard-extension/package.json`
+   * via Node's module resolver. Return the absolute package.json path
+   * or null. Defaults to `createRequire(import.meta.url).resolve(...)`.
+   */
+  resolvePackage?: () => string | null;
+}
+
+function defaultResolvePackage(): string | null {
+  try {
+    const req = createRequire(import.meta.url);
+    return req.resolve("@blackbelt-technology/pi-dashboard-extension/package.json");
+  } catch {
     return null;
   }
+}
+
+/**
+ * Find the bundled extension directory.
+ *
+ * Resolution order:
+ *   1. Monorepo layout: `<baseDir>/packages/extension/`.
+ *   2. Node module resolution: `@blackbelt-technology/pi-dashboard-extension/package.json`
+ *      via `require.resolve` from this module. Works in ANY install layout
+ *      (flat `node_modules/`, scoped, nested, pnpm, npm-g). This is the
+ *      canonical identity-based lookup and the only reliable strategy
+ *      when pi-dashboard is installed via `npm i -g`.
+ *
+ * Returns null if both strategies fail, the resolved directory doesn't
+ * have a package.json, or the path is under /tmp/.mount_* (AppImage).
+ *
+ * See change: unified-bootstrap-install.
+ */
+export function findBundledExtension(
+  baseDir: string,
+  deps: FindExtensionDeps = {},
+): string | null {
+  // Strategy 1: monorepo sibling layout.
+  const monorepoCandidate = path.resolve(baseDir, "packages", "extension");
+  if (isValidExtensionPath(monorepoCandidate)) return monorepoCandidate;
+
+  // Strategy 2: Node module resolver. This works for the `npm i -g
+  // pi-dashboard` layout where the extension is shipped as a runtime dep
+  // of pi-dashboard-server.
+  const resolver = deps.resolvePackage ?? defaultResolvePackage;
+  const extPkgJson = resolver();
+  if (extPkgJson) {
+    const extDir = path.dirname(extPkgJson);
+    if (isValidExtensionPath(extDir)) return extDir;
+  }
+
+  return null;
+}
 
-  return candidate;
+/** Optional overrides for testing / multi-HOME scenarios. */
+export interface BridgeRegisterOptions {
+  /**
+   * Override the HOME used to locate settings.json. When omitted,
+   * falls back to `$HOME || $USERPROFILE || os.homedir()` (existing behavior).
+   */
+  homedir?: string;
 }
 
 /**
@@ -44,12 +107,16 @@ export function findBundledExtension(baseDir: string): string | null {
  *
  * No-op if the path is already registered.
  */
-export function registerBridgeExtension(extensionPath: string): void {
+export function registerBridgeExtension(
+  extensionPath: string,
+  opts: BridgeRegisterOptions = {},
+): void {
   // Compute at call time so tests can override HOME
-  const settingsPath = path.join(
-    process.env.HOME || process.env.USERPROFILE || os.homedir(),
-    ".pi", "agent", "settings.json",
-  );
+  const home = opts.homedir
+    ?? process.env.HOME
+    ?? process.env.USERPROFILE
+    ?? os.homedir();
+  const settingsPath = path.join(home, ".pi", "agent", "settings.json");
   const settingsDir = path.dirname(settingsPath);
   fs.mkdirSync(settingsDir, { recursive: true });