@lincoln504/pi-research 1.7.8 → 1.7.10

package/src/infrastructure/browser/camoufox-layout.ts

@@ -0,0 +1,450 @@
+/**
+ * Camoufox install-layout helpers for the runtime (ensure-browser, config, cli).
+ *
+ * TWIN of scripts/camoufox-layout.cjs (the install/uninstall half). The two
+ * are kept equivalent on purpose and test/unit/infrastructure/
+ * camoufox-layout.test.ts runs both against the same fixtures, because a drift
+ * between "where setup installed it" and "where the runtime looks" is exactly the
+ * install/runtime mismatch this package has shipped before.
+ *
+ * Why this exists. `@camoufox/camoufox` (0.5.x) differs from the old `camoufox-js`:
+ *   - It installs under  <INSTALL_DIR>/browsers/<repo>/<version>/  (multi-version),
+ *     with `config.json`, `repo_cache.json` and a `.0.5_FLAG` beside it. camoufox-js
+ *     put the browser files FLAT in INSTALL_DIR with a root `version.json`.
+ *   - INSTALL_DIR is derived ONLY from platform cache dirs (XDG_CACHE_HOME on Linux,
+ *     LOCALAPPDATA on Windows, $HOME/Library/Caches on macOS). It does NOT read
+ *     CAMOUFOX_INSTALL_DIR or PLAYWRIGHT_BROWSERS_PATH.
+ *   - `camoufox fetch` does `rm -rf INSTALL_DIR` when it is non-empty and has no
+ *     `.0.5_FLAG` ("Cleaning old data...") BEFORE it downloads anything, so a failed
+ *     download over a legacy install leaves the user with no browser at all.
+ *   - A newer pi-research release that pins a newer browser installs the new build
+ *     beside the old one and never removes it; the old one is dead weight because a
+ *     released library only ever launches its own pinned build.
+ */
+
+import * as fs from 'node:fs';
+import * as os from 'node:os';
+import * as path from 'node:path';
+import { createRequire } from 'node:module';
+
+export const COMPAT_FLAG = '.0.5_FLAG';
+
+/** Names whose presence, with a root version.json, proves a legacy camoufox-js install. */
+const LEGACY_MARKERS = ['camoufox-bin', 'camoufox', 'camoufox.exe', 'application.ini', 'Camoufox.app', 'properties.json'];
+
+function isDir(p: string): boolean {
+  try {
+    return fs.statSync(p).isDirectory();
+  } catch {
+    return false;
+  }
+}
+
+function isFile(p: string): boolean {
+  try {
+    return fs.statSync(p).isFile();
+  } catch {
+    return false;
+  }
+}
+
+/** The custom location the user asked for, if any (camoufox itself ignores both variables). */
+export function customDir(env: NodeJS.ProcessEnv = process.env): string | null {
+  return env['CAMOUFOX_INSTALL_DIR'] || env['PLAYWRIGHT_BROWSERS_PATH'] || null;
+}
+
+/** Mirrors @camoufox/camoufox paths.js userCacheDir('camoufox') for a given environment. */
+export function defaultInstallDir(env: NodeJS.ProcessEnv = process.env, platform: NodeJS.Platform = process.platform, home: string = os.homedir()): string {
+  if (platform === 'win32') {
+    const base = env['LOCALAPPDATA'] && path.win32.isAbsolute(env['LOCALAPPDATA'])
+      ? env['LOCALAPPDATA']
+      : path.join(home, 'AppData', 'Local');
+    return path.join(base, 'camoufox', 'camoufox', 'Cache');
+  }
+  if (platform === 'darwin') return path.join(home, 'Library', 'Caches', 'camoufox');
+  const xdg = (env['XDG_CACHE_HOME'] || '').trim();
+  return path.join(xdg ? xdg : path.join(home, '.cache'), 'camoufox');
+}
+
+/**
+ * Resolve where the browser lives and which env overrides make camoufox use it.
+ *
+ *  - No custom dir:  the platform default, no overrides.
+ *  - Linux:   custom is the cache HOME (XDG_CACHE_HOME=custom, browser in custom/camoufox),
+ *             except when custom already ends in `camoufox`, where its parent becomes the
+ *             cache home so the browser lives in custom itself (old camoufox-js semantics).
+ *  - Windows: same idea through LOCALAPPDATA (browser in <base>\camoufox\camoufox\Cache).
+ *  - macOS:   camoufox derives the cache from $HOME only; relocating it would mean
+ *             redirecting HOME for the browser process, which also moves Firefox's own
+ *             state. The custom dir is ignored there (`ignoredCustom` is set so callers can say so).
+ */
+export interface ResolvedInstall {
+  dir: string;
+  overrides: Record<string, string>;
+  custom: string | null;
+  ignoredCustom: boolean;
+}
+
+export function resolveInstall(env: NodeJS.ProcessEnv = process.env, platform: NodeJS.Platform = process.platform, home: string = os.homedir()): ResolvedInstall {
+  const custom = customDir(env);
+  if (!custom) return { dir: defaultInstallDir(env, platform, home), overrides: {}, custom: null, ignoredCustom: false };
+  if (platform === 'darwin') {
+    return { dir: defaultInstallDir(env, platform, home), overrides: {}, custom, ignoredCustom: true };
+  }
+  const resolved = (platform === 'win32' ? path.win32 : path).resolve(custom);
+  if (platform === 'win32') {
+    // <LOCALAPPDATA>\camoufox\camoufox\Cache : one fixed shape, custom = LOCALAPPDATA.
+    const overrides: Record<string, string> = { LOCALAPPDATA: resolved };
+    return { dir: defaultInstallDir({ ...env, ...overrides }, platform, home), overrides, custom, ignoredCustom: false };
+  }
+  const endsInCamoufox = path.basename(resolved).toLowerCase() === 'camoufox';
+  const cacheHome = endsInCamoufox ? path.dirname(resolved) : resolved;
+  const overrides: Record<string, string> = { XDG_CACHE_HOME: cacheHome };
+  return { dir: defaultInstallDir({ ...env, ...overrides }, platform, home), overrides, custom, ignoredCustom: false };
+}
+
+/** Every `browsers/<repo>/<version>/` directory that holds a parseable version.json. */
+export interface InstalledBuild { repo: string; name: string; path: string; rel: string; version: string; build: string }
+
+/** The browser build @camoufox/camoufox was released with (repoName lowercased). */
+export interface BrowserPin { repoName: string; version: string; build: string }
+
+export function listInstalls(dir: string): InstalledBuild[] {
+  const out: InstalledBuild[] = [];
+  const browsers = path.join(dir, 'browsers');
+  let repos: fs.Dirent[];
+  try {
+    repos = fs.readdirSync(browsers, { withFileTypes: true });
+  } catch {
+    return out;
+  }
+  for (const repo of repos) {
+    if (!repo.isDirectory() || repo.name.startsWith('.')) continue;
+    const repoDir = path.join(browsers, repo.name);
+    let versions: fs.Dirent[];
+    try {
+      versions = fs.readdirSync(repoDir, { withFileTypes: true });
+    } catch {
+      continue;
+    }
+    for (const v of versions) {
+      if (!v.isDirectory()) continue;
+      const vdir = path.join(repoDir, v.name);
+      let meta: { version?: unknown; build?: unknown } | null;
+      try {
+        meta = JSON.parse(fs.readFileSync(path.join(vdir, 'version.json'), 'utf8')) as { version?: unknown; build?: unknown } | null;
+      } catch {
+        continue; // missing/corrupt version.json: the library skips it too
+      }
+      out.push({
+        repo: repo.name,
+        name: v.name,
+        path: vdir,
+        rel: `browsers/${repo.name}/${v.name}`,
+        version: meta && typeof meta.version === 'string' ? meta.version : '',
+        build: meta && typeof meta.build === 'string' ? meta.build : '',
+      });
+    }
+  }
+  return out;
+}
+
+/** True when the NEW layout holds at least one usable browser version. */
+export function hasInstall(dir: string): boolean {
+  return listInstalls(dir).length > 0;
+}
+
+/**
+ * Proof that `dir` is a legacy flat camoufox-js install: a root version.json carrying
+ * `version` + `release`, no `.0.5_FLAG`, and at least one file only a camoufox build has.
+ * Anything short of that is NOT claimed, so it is never removed or moved.
+ */
+export function isLegacyFlat(dir: string): boolean {
+  if (!isDir(dir) || isFile(path.join(dir, COMPAT_FLAG))) return false;
+  let meta: { version?: unknown; release?: unknown } | null;
+  try {
+    meta = JSON.parse(fs.readFileSync(path.join(dir, 'version.json'), 'utf8')) as typeof meta;
+  } catch {
+    return false;
+  }
+  if (!meta || typeof meta.version !== 'string' || typeof meta.release !== 'string') return false;
+  return LEGACY_MARKERS.some((m) => fs.existsSync(path.join(dir, m)));
+}
+
+/**
+ * Whether `dir` is provably camoufox's own install dir (new or legacy layout, or the
+ * empty shell camoufox leaves behind). Used as the guard before any recursive delete.
+ */
+export function isCamoufoxDir(dir: string): boolean {
+  if (!isDir(dir)) return false;
+  if (isFile(path.join(dir, COMPAT_FLAG))) return true;
+  if (hasInstall(dir)) return true;
+  if (isLegacyFlat(dir)) return true;
+  return false;
+}
+
+/** True when the user chose a channel/pin themselves (camoufox then honours it, so keep their versions). */
+export function hasExplicitChoice(dir: string): boolean {
+  try {
+    const cfg = JSON.parse(fs.readFileSync(path.join(dir, 'config.json'), 'utf8')) as { pinned?: string; channel?: string } | null;
+    return Boolean(cfg && (cfg.pinned || cfg.channel));
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * The browser build @camoufox/camoufox was released with, from its browser-pin.json,
+ * or null when unpinned/unreadable. `packageRoot` is the @camoufox/camoufox directory.
+ */
+export function loadPin(packageRoot: string): BrowserPin | null {
+  try {
+    const data = JSON.parse(fs.readFileSync(path.join(packageRoot, 'dist', 'data-files', 'browser-pin.json'), 'utf8')) as { tag?: string; repo_name?: unknown; version?: unknown; build?: unknown } | null;
+    if (!data || !data.tag) return null;
+    return { repoName: String(data.repo_name).toLowerCase(), version: String(data.version), build: String(data.build) };
+  } catch {
+    return null;
+  }
+}
+
+/** The @camoufox/camoufox package directory as seen from `fromUrl`, or null. */
+export function findPackageRoot(fromUrl: string): string | null {
+  try {
+    const require = createRequire(fromUrl);
+    return path.dirname(require.resolve('@camoufox/camoufox/package.json'));
+  } catch {
+    return null;
+  }
+}
+
+/** Whether `build` is the one `pin` names. */
+export function matchesPin(build: InstalledBuild, pin: BrowserPin): boolean {
+  return build.repo.toLowerCase() === pin.repoName && build.version === pin.version && build.build === pin.build;
+}
+
+/**
+ * Remove every installed version except the one the library will launch: the paired
+ * build when `pin` is given and the user made no explicit choice, otherwise the active one. A released camoufox launches
+ * only the build it was released with, so superseded builds are pure disk weight.
+ * Does nothing when the user made an explicit `camoufox set` choice, when there is no
+ * identifiable active version, or when the active version's folder is missing.
+ * Returns the removed relative paths.
+ */
+export function pruneSuperseded(dir: string, log: (m: string) => void = () => {}, pin: BrowserPin | null = null): string[] {
+  if (hasExplicitChoice(dir)) return [];
+  const installs = listInstalls(dir);
+  let keep: string | null = null;
+  if (pin) {
+    const paired = installs.find((i) => matchesPin(i, pin));
+    keep = paired ? paired.rel : null;
+  } else {
+    try {
+      keep = (JSON.parse(fs.readFileSync(path.join(dir, 'config.json'), 'utf8')) as { active_version?: string }).active_version || null;
+    } catch {
+      return [];
+    }
+  }
+  if (!keep || !installs.some((i) => i.rel === keep)) return [];
+  const removed: string[] = [];
+  for (const i of installs) {
+    if (i.rel === keep) continue;
+    try {
+      fs.rmSync(i.path, { recursive: true, force: true });
+      removed.push(i.rel);
+      log(`pi-research: removed superseded Camoufox build ${i.rel}`);
+    } catch (e) {
+      log(`pi-research: could not remove superseded Camoufox build ${i.rel}: ${e instanceof Error ? e.message : String(e)}`);
+    }
+  }
+  // Drop now-empty repo folders so listings stay clean.
+  try {
+    for (const r of fs.readdirSync(path.join(dir, 'browsers'))) {
+      const rd = path.join(dir, 'browsers', r);
+      if (isDir(rd) && fs.readdirSync(rd).length === 0) fs.rmdirSync(rd);
+    }
+  } catch { /* best effort */ }
+  return removed;
+}
+
+/**
+ * Move a PROVEN legacy flat install out of the way so `camoufox fetch` (which would
+ * rm -rf it before downloading) cannot destroy a working browser if the download fails.
+ * Returns the stash path, or null when `dir` is not a provable legacy install.
+ */
+export function stashLegacy(dir: string): string | null {
+  if (!isLegacyFlat(dir)) return null;
+  const stash = `${dir}.legacy-${process.pid}-${Date.now()}`;
+  fs.renameSync(dir, stash);
+  return stash;
+}
+
+/** Put a stashed legacy install back (download failed). */
+export function restoreLegacy(dir: string, stash: string | null): void {
+  if (!stash || !fs.existsSync(stash)) return;
+  try {
+    fs.rmSync(dir, { recursive: true, force: true });
+  } catch { /* partial new dir; best effort */ }
+  fs.renameSync(stash, dir);
+}
+
+/** Delete a stashed legacy install (new layout verified usable). */
+export function discardLegacy(stash: string | null): void {
+  if (!stash) return;
+  fs.rmSync(stash, { recursive: true, force: true });
+}
+
+/** Leftover legacy stash dirs from a crashed run next to `dir`; deleted only when the new layout is usable. */
+export function sweepStaleStashes(dir: string, log: (m: string) => void = () => {}): string[] {
+  if (!hasInstall(dir)) return [];
+  const parent = path.dirname(dir);
+  const prefix = `${path.basename(dir)}.legacy-`;
+  const removed: string[] = [];
+  let entries: string[];
+  try {
+    entries = fs.readdirSync(parent);
+  } catch {
+    return removed;
+  }
+  for (const e of entries) {
+    if (!e.startsWith(prefix)) continue;
+    const p = path.join(parent, e);
+    if (!isLegacyFlat(p)) continue;
+    try {
+      fs.rmSync(p, { recursive: true, force: true });
+      removed.push(p);
+      log(`pi-research: removed leftover legacy Camoufox stash ${p}`);
+    } catch { /* best effort */ }
+  }
+  return removed;
+}
+
+/**
+ * Remove the whole install dir, but only when it is provably camoufox's own.
+ * Returns 'removed' | 'absent' | 'refused'.
+ */
+export function removeInstallDir(dir: string): 'removed' | 'absent' | 'refused' {
+  if (!fs.existsSync(dir)) return 'absent';
+  if (!isCamoufoxDir(dir)) return 'refused';
+  fs.rmSync(dir, { recursive: true, force: true });
+  return 'removed';
+}
+
+/** True when the NEW layout can launch: the compat flag plus the paired build (or any build when unpinned). */
+export function isUsable(dir: string, pin: BrowserPin | null = null): boolean {
+  if (!isFile(path.join(dir, COMPAT_FLAG))) return false;
+  const installs = listInstalls(dir);
+  if (installs.length === 0) return false;
+  // A released library launches ONLY its paired build (unless the user chose one with
+  // `camoufox set`), and downloads it itself if absent. So "usable" means the paired
+  // build is there, which makes an upgrade to a new pin re-fetch centrally instead of in
+  // every worker at once.
+  if (pin && !hasExplicitChoice(dir)) return installs.some((i) => matchesPin(i, pin));
+  return true;
+}
+
+/** Stash dirs (`<dir>.legacy-<pid>-<ts>`) left beside `dir`, newest first, each proven legacy. */
+export function listStashes(dir: string): string[] {
+  const parent = path.dirname(dir);
+  const prefix = `${path.basename(dir)}.legacy-`;
+  let entries: string[];
+  try {
+    entries = fs.readdirSync(parent);
+  } catch {
+    return [];
+  }
+  return entries
+    .filter((e) => e.startsWith(prefix))
+    .map((e) => path.join(parent, e))
+    .filter((p) => isLegacyFlat(p))
+    .sort()
+    .reverse();
+}
+
+/**
+ * Crash recovery: a previous run moved a legacy install aside and died before the
+ * new build landed. If `dir` is now absent/empty and a proven legacy stash exists,
+ * put it back so the user is not left without a browser. Returns the restored stash or null.
+ */
+export function recoverStash(dir: string, log: (m: string) => void = () => {}): string | null {
+  let empty = !fs.existsSync(dir);
+  if (!empty) {
+    try {
+      empty = isDir(dir) && fs.readdirSync(dir).length === 0;
+    } catch {
+      return null;
+    }
+  }
+  if (!empty) return null;
+  const stash = listStashes(dir)[0];
+  if (!stash) return null;
+  try {
+    if (fs.existsSync(dir)) fs.rmdirSync(dir);
+    fs.renameSync(stash, dir);
+    log(`pi-research: restored the previous Camoufox install from ${stash}`);
+    return stash;
+  } catch {
+    return null;
+  }
+}
+
+export interface ProvisionResult {
+  status: 'present' | 'installed' | 'failed';
+  pruned: string[];
+  reason?: string;
+}
+
+/**
+ * Install the pinned browser without ever leaving the user with less than they had.
+ *
+ * `camoufox fetch` (and the library's own first launch) run `rm -rf <dir>` on a
+ * non-empty dir that has no compat flag, i.e. on every legacy flat install, BEFORE
+ * downloading. So a legacy install is moved aside first, the fetch runs against a clean
+ * dir, and the stash is deleted only after the new layout verifies usable; any failure
+ * restores it. `fetch` resolves true when the fetch process exited 0.
+ */
+export async function provisionBrowser(
+  dir: string,
+  fetch: () => Promise<boolean>,
+  log: (m: string) => void = () => {},
+  pin: BrowserPin | null = null,
+): Promise<ProvisionResult> {
+  recoverStash(dir, log);
+  if (isUsable(dir, pin)) {
+    sweepStaleStashes(dir, log);
+    return { status: 'present', pruned: pruneSuperseded(dir, log, pin) };
+  }
+  let stash: string | null;
+  try {
+    stash = stashLegacy(dir);
+  } catch (e) {
+    // Could not move it (in use on Windows, permissions): fetching now would delete it.
+    return { status: 'failed', pruned: [], reason: `could not move the existing legacy install aside (${e instanceof Error ? e.message : String(e)}); left untouched` };
+  }
+  if (stash) log(`pi-research: legacy Camoufox install moved aside to ${stash} until the new browser is verified`);
+  let ok = false;
+  let reason: string | undefined;
+  try {
+    ok = (await fetch()) === true;
+    if (!ok) reason = 'camoufox fetch did not exit 0';
+  } catch (e) {
+    reason = e instanceof Error ? e.message : String(e);
+  }
+  // A non-zero exit is NOT proof the browser is unusable. The launcher extracts the
+  // browser and writes the compat flag BEFORE it fetches its companion geoip database
+  // from a separate GitHub release, so a failure there (observed: `UND_ERR_SOCKET other
+  // side closed` on ubuntu-latest, three runs in a row on 2026-10-05) exits non-zero with
+  // a fully launchable paired build already in place. Verified: a real headless launch
+  // succeeds with the mmdb removed. Keep the install and drop the legacy stash rather
+  // than reporting a failure and restoring an older browser on top of a working one.
+  if (isUsable(dir, pin)) {
+    discardLegacy(stash);
+    if (stash) log('pi-research: removed the legacy Camoufox install (replaced by the new build)');
+    if (!ok) log(`pi-research: camoufox fetch reported a failure after the browser was installed (${reason}); keeping it. Run "npx camoufox fetch" to retry the companion download (e.g. the geoip database).`);
+    sweepStaleStashes(dir, log);
+    return { status: 'installed', pruned: pruneSuperseded(dir, log, pin) };
+  }
+  if (ok) reason = 'camoufox fetch exited 0 but no usable build was found';
+  restoreLegacy(dir, stash);
+  if (stash) log('pi-research: restored the previous Camoufox install after a failed upgrade');
+  return { status: 'failed', pruned: [], reason };
+}

package/src/infrastructure/browser/config.ts

@@ -9,6 +9,7 @@ import * as crypto from 'node:crypto';
 import { join } from 'node:path';
 import { existsSync, mkdirSync } from 'node:fs';
 import { platform, homedir } from 'node:os';
+import { resolveInstall, isUsable, loadPin, findPackageRoot } from './camoufox-layout.ts';
 import type { Config } from '../../config.ts';
 import { getConfig } from '../../config.ts';
 import { getLogger } from '../../logger.ts';
@@ -19,63 +20,26 @@ import { createRequire } from 'node:module';
 // ============================================================================
 
 /**
- * The directory where camoufox-js installs the browser on Windows.
+ * Where the Camoufox browser lives, and which environment overrides make the
+ * browser launcher agree with that.
  *
- * camoufox-js's userCacheDir("camoufox") resolves to
- *   os.homedir()/AppData/Local/camoufox/camoufox/Cache
- * — note the DOUBLED "camoufox" segment, and that it uses os.homedir() rather
- * than %LOCALAPPDATA%. We must mirror it exactly, otherwise isBrowserAvailable()
- * looks in the wrong place and every browser test silently skips on Windows
- * even though the binary downloaded and launches fine.
+ * `@camoufox/camoufox` derives its install directory ONLY from the platform cache
+ * location (XDG_CACHE_HOME on Linux, LOCALAPPDATA on Windows, $HOME/Library/Caches on
+ * macOS). Unlike the camoufox-js it replaced, it does NOT read CAMOUFOX_INSTALL_DIR
+ * or PLAYWRIGHT_BROWSERS_PATH. Both variables are still honoured here as the
+ * documented way to relocate the browser, by translating them into the platform
+ * override the launcher does read (see resolveInstall in camoufox-layout.ts). The
+ * lookup (getCamoufoxBinaryPath), the install (scripts/setup.cjs,
+ * ensure-browser.ts) and the worker launch (getBrowserEnv) all go through that one
+ * function, so they cannot disagree.
  */
-function getWindowsCamoufoxDir(): string {
-    return join(homedir(), 'AppData', 'Local', 'camoufox', 'camoufox', 'Cache');
-}
-
-/**
- * The custom camoufox location, if the user set one.
- *
- * CAMOUFOX_INSTALL_DIR takes precedence because it is camoufox-js's OWN
- * variable and the only one that can ever move the install: camoufox-js ≥0.12.0
- * resolves INSTALL_DIR from it. PLAYWRIGHT_BROWSERS_PATH is kept as a documented
- * alias, but on its own it only ever moved where we LOOK — camoufox went on
- * installing to the default cache, so setting it made the browser permanently
- * "not found" right after a successful download. Both are exported onward to
- * camoufox-js (getBrowserEnv, scripts/setup.cjs) so that install and lookup
- * cannot disagree.
- *
- * HISTORY: camoufox-js <0.12.0 hardcoded `userCacheDir("camoufox")` and
- * honoured NEITHER variable, which made this plumbing deliberately inert for
- * two pin cycles. The 0.12.0 refresh (2026-08-30) honours CAMOUFOX_INSTALL_DIR
- * again, so a custom location now relocates the install itself, not just our
- * lookup — the two can no longer disagree via version skew, but keep the dual
- * export (install + lookup) so they can never drift apart in future.
- */
-function getCustomCamoufoxDir(): string | undefined {
-    return process.env['CAMOUFOX_INSTALL_DIR'] || process.env['PLAYWRIGHT_BROWSERS_PATH'] || undefined;
-}
 
 /**
- * Get the camoufox binary cache directory.
- * Uses the custom location above if set, otherwise the standard user cache location
- * that camoufox uses by default (~/.cache/camoufox on Linux).
+ * Get the camoufox install directory (the directory that holds `browsers/`).
  * We do NOT override HOME — that trick was unreliable and caused install/runtime mismatches.
  */
 export function getBrowserCacheDir(): string {
-    const custom = getCustomCamoufoxDir();
-    if (custom) {
-        return custom;
-    }
-    // Mirror getCamoufoxBinaryPath() so both functions agree on the cache location
-    const osPlatform = platform();
-    if (osPlatform === 'win32') {
-        return getWindowsCamoufoxDir();
-    } else if (osPlatform === 'darwin') {
-        return join(homedir(), 'Library', 'Caches', 'camoufox');
-    } else {
-        const cacheHome = process.env['XDG_CACHE_HOME'] || join(homedir(), '.cache');
-        return join(cacheHome, 'camoufox');
-    }
+    return resolveInstall(process.env, platform(), homedir()).dir;
 }
 
 /**
@@ -134,18 +98,16 @@ export function getBrowserProfileDir(config?: Config): string {
  */
 export function getBrowserEnv(config?: Config): NodeJS.ProcessEnv {
     const env: NodeJS.ProcessEnv = { ...process.env };
-    const customPath = getCustomCamoufoxDir();
-    if (customPath) {
-        env['PLAYWRIGHT_BROWSERS_PATH'] = customPath;
-        // The one that camoufox-js actually reads. Without it the worker's
-        // camoufox launches from the DEFAULT cache while everything on this side
-        // resolves the custom path — the install/runtime mismatch this file's
-        // header warns about, just arriving through a different door.
-        env['CAMOUFOX_INSTALL_DIR'] = customPath;
-    } else {
-        delete env['PLAYWRIGHT_BROWSERS_PATH'];
-        delete env['CAMOUFOX_INSTALL_DIR'];
-    }
+    // Hand the worker the placement overrides the browser launcher actually reads
+    // (XDG_CACHE_HOME / LOCALAPPDATA), derived from the user's custom dir. Without
+    // them the worker launches from the DEFAULT cache while everything on this side
+    // resolves the custom one: the install/runtime mismatch this file's header warns
+    // about. The two user-facing variables are removed so a nested tool cannot
+    // reinterpret them.
+    const install = resolveInstall(process.env, platform(), homedir());
+    Object.assign(env, install.overrides);
+    delete env['PLAYWRIGHT_BROWSERS_PATH'];
+    delete env['CAMOUFOX_INSTALL_DIR'];
     // Tell thread-workers where to write their lifecycle/error log. Precedence:
     //   1. A user-set PI_RESEARCH_LOG_FILE (already copied from process.env above) wins —
     //      never clobber an explicit override.
@@ -194,26 +156,12 @@ export function ensureBrowserCacheDir(): string {
 }
 
 /**
- * Get the expected path where camoufox installs its binaries.
- * Matches camoufox-js's own resolution logic.
+ * Get the path where camoufox installs its browsers (the directory holding `browsers/`).
+ * Same answer as getBrowserCacheDir(); kept as a separate name for the callers that
+ * think of it as "the binary location".
  */
 export function getCamoufoxBinaryPath(): string {
-    const customPath = getCustomCamoufoxDir();
-    if (customPath) {
-        return customPath;
-    }
-
-    const osPlatform = platform();
-
-    if (osPlatform === 'win32') {
-        return getWindowsCamoufoxDir();
-    } else if (osPlatform === 'darwin') {
-        return join(homedir(), 'Library', 'Caches', 'camoufox');
-    } else {
-        // Linux and others
-        const cacheHome = process.env['XDG_CACHE_HOME'] || join(homedir(), '.cache');
-        return join(cacheHome, 'camoufox');
-    }
+    return getBrowserCacheDir();
 }
 
 // ============================================================================
@@ -255,7 +203,7 @@ export function getSchedulerVersion(config?: Config): string {
  *
  * Returns true (true headless — no visible window) on Windows and macOS.
  * Historically Windows used headless:false because headless:true crashed Firefox
- * (exit 0x80000003, camoufox-js issue #614); that is fixed in camoufox-js >=0.10
+ * (exit 0x80000003, camoufox issue #614); that is fixed in camoufox-js >=0.10
  * (verified on Windows 11 x64 with 0.10.2: headless:true launches and navigates
  * reliably and, crucially, NO browser window pops up on the desktop). Using
  * headless:false on a real Windows desktop flashed visible, sometimes fullscreen,
@@ -302,8 +250,8 @@ export function resolveHeadlessMode(): boolean | 'virtual' {
  * Check if the browser is available for meaningful browser pool testing.
  * 
  * Returns false if:
- * - camoufox-js package is not installed
- * - camoufox binary is not present at expected path
+ * - @camoufox/camoufox package is not installed
+ * - no browser build is installed under the cache dir (new `browsers/<repo>/<version>` layout)
  * - FULL_MOCK_MODE is active (both search and scrape mocked)
  * 
  * In FULL_MOCK_MODE, browser pool tests are not meaningful because:
@@ -317,22 +265,16 @@ export function resolveHeadlessMode(): boolean | 'virtual' {
  * Whether the browser stack's NATIVE dependencies can actually load.
  *
  * `isBrowserAvailable()` answers a different question — is the camoufox binary on
- * disk — and a browser can be fully downloaded and still unable to launch. camoufox-js
- * requires `better-sqlite3`, whose binding is produced by a dependency INSTALL SCRIPT,
- * and npm 12 turns those off by default. The module then imports fine and throws only
- * when first used, so nothing notices until every browser worker dies mid-run with
- * "Could not locate the bindings file" and the run reports a network problem it does
- * not have.
- *
- * Measured, not assumed: of this package's native dependencies, only better-sqlite3
- * fails a scripts-blocked install. onnxruntime-node ships its binding inside its own
- * tarball, and lancedb, impit and html-to-markdown all resolve prebuilt platform
- * packages, so the knowledge store keeps working while search is dead — exactly the
- * split seen in the field.
+ * disk — and a browser can be fully downloaded and still unable to launch.
  *
- * Opening an in-memory database is the only check that settles it: resolving the
- * module or stat-ing a path does not, because the failure is in the binding lookup at
- * first use. It costs a few milliseconds and is confined to diagnostics.
+ * History: camoufox-js required `better-sqlite3`, whose binding came from a dependency
+ * INSTALL SCRIPT that npm 12 turns off, so the module imported fine and every browser
+ * worker died at first use. `@camoufox/camoufox` has no better-sqlite3; the one native
+ * module left in the launcher's path is `impit` (its IP/geo lookups), which resolves a
+ * prebuilt platform package. That package can still be dropped by npm's optional-
+ * dependency bug (npm/cli#4828), and the failure is again at first use, so the probe
+ * loads it: resolving the module name or stat-ing a path does not settle it. It costs a
+ * few milliseconds and is confined to diagnostics.
  */
 export function probeBrowserNativeDeps(
     /** Injected for tests. Production callers pass nothing. */
@@ -350,16 +292,17 @@ export function probeBrowserNativeDeps(
 
 function defaultNativeDepLoad(): void {
     const require = createRequire(import.meta.url);
-    const Database = require('better-sqlite3') as new (p: string) => { close(): void };
-    const db = new Database(':memory:');
-    db.close();
+    // Requiring `impit` loads its native binding eagerly and throws if the platform
+    // package is missing.
+    require('impit');
 }
 
 export function isBrowserAvailable(): boolean {
     if (isFullMockMode()) return false;
     try {
-        import.meta.resolve('camoufox-js');
-        return existsSync(getCamoufoxBinaryPath());
+        import.meta.resolve('@camoufox/camoufox');
+        const root = findPackageRoot(import.meta.url);
+        return isUsable(getCamoufoxBinaryPath(), root ? loadPin(root) : null);
     } catch {
         return false;
     }