@lincoln504/pi-research 1.3.10 → 1.3.12

package/src/cli.ts

@@ -44,6 +44,8 @@ import { exportResearchReport, appendExportMessage } from './utils/research-expo
 import { getConfig, getGlobalConfigDir, getGlobalEnvFilePath, getInterfaceEnvFilePath, getStateDir, saveConfig, resetConfig, describeKnowledgeStoreMode, isProjectScopedKey, parseDotEnv } from './config.ts';
 import { getAgentDir } from '@earendil-works/pi-coding-agent';
 import { buildModelRegistry, safeGetAvailable } from './core/llm/model-registry-factory.ts';
+import { RESEARCH_TOOL_NAMES } from './constants.ts';
+import { isBrowserAvailable } from './infrastructure/browser/config.ts';
 
 // ---------------------------------------------------------------------------
 // Constants
@@ -234,7 +236,8 @@ export class ConfigFileError extends Error {}
  * the real environment, so real shell exports always win.
  */
 export function bridgeConfigEnv(explicitConfigPath?: string): { path: string; loaded: boolean } {
-  const basePath = explicitConfigPath ?? getGlobalEnvFilePath();
+  const globalBasePath = getGlobalEnvFilePath();
+  const basePath = explicitConfigPath ?? globalBasePath;
   const cliOverlayPath = getInterfaceEnvFilePath('cli');
   let loaded = false;
   // Merge base then overlay into one map FIRST (overlay wins), and only then
@@ -252,13 +255,18 @@ export function bridgeConfigEnv(explicitConfigPath?: string): { path: string; lo
   // the user passed on this exact invocation is the most specific intent, and the
   // ambient cli.env overlay silently overriding it re-created the very failure
   // this bridge exists to fix (a key set in `--config ci.env` simply not applying).
+  // The GLOBAL base always stays underneath: this bridge exists for env-only keys
+  // (PI_RESEARCH_API_KEY & co.) that getConfig never carries, so dropping the base
+  // here silently dropped credentials stored only in config.env — `--config extra.env`
+  // exit-78'd on a correctly configured machine while the help text promised
+  // "base config.env keys it does not set still apply".
   const layers = explicitConfigPath !== undefined
-    ? [cliOverlayPath, basePath]
-    : [basePath, cliOverlayPath];
+    ? [globalBasePath, cliOverlayPath, explicitConfigPath]
+    : [globalBasePath, cliOverlayPath];
   for (const filePath of layers) {
     // Only the EXPLICIT --config file fails loudly (see ConfigFileError above);
     // the ambient layers keep their missing/unreadable tolerance unchanged.
-    const isExplicit = explicitConfigPath !== undefined && filePath === basePath;
+    const isExplicit = explicitConfigPath !== undefined && filePath === explicitConfigPath;
     try {
       if (!fs.existsSync(filePath)) {
         if (isExplicit) throw new ConfigFileError(`--config file not found: ${filePath}`);
@@ -495,11 +503,20 @@ async function detectCredentials(explicitModel?: string): Promise<CredentialDete
     modelFrom,
     piAuthPresent,
     piModelsPresent,
-    problem:
-      'No model or API key is configured for pi-research. Provide credentials via environment ' +
-      'variables (PI_RESEARCH_API_KEY + PI_RESEARCH_PROVIDER + PI_RESEARCH_MODEL) or, if you use ' +
-      "pi, via pi's configuration (a provider entry in ~/.pi/agent/auth.json, or a per-provider " +
-      'apiKey in ~/.pi/agent/models.json).',
+    // A model configured with no usable key is a different (and misleading to
+    // conflate) gap than nothing configured at all: SKILL.md tells agents to relay
+    // this text verbatim, so "No model … is configured" pointed users who HAD set
+    // PI_RESEARCH_MODEL at the wrong knob.
+    problem: model
+      ? `A model is configured (${model}) but no API key is available for ` +
+        `${provider ? `provider "${provider}"` : 'its provider'}. Provide one via the ` +
+        'PI_RESEARCH_API_KEY environment variable (with PI_RESEARCH_PROVIDER), or, if you use pi, ' +
+        "via pi's configuration (a provider entry in ~/.pi/agent/auth.json, or a per-provider " +
+        'apiKey in ~/.pi/agent/models.json).'
+      : 'No model or API key is configured for pi-research. Provide credentials via environment ' +
+        'variables (PI_RESEARCH_API_KEY + PI_RESEARCH_PROVIDER + PI_RESEARCH_MODEL) or, if you use ' +
+        "pi, via pi's configuration (a provider entry in ~/.pi/agent/auth.json, or a per-provider " +
+        'apiKey in ~/.pi/agent/models.json).',
   };
 }
 
@@ -604,6 +621,14 @@ export async function cmdResearch(args: ResearchArgs): Promise<number> {
       ...(args.initialLinks ? { initialLinks: args.initialLinks } : {}),
     }, abortController.signal);
 
+    // Snapshot the run diagnostics NOW, before any further await: on a cancelled
+    // run, onSignal's fire-and-forget safeShutdown runs concurrently with this
+    // tail and resets these SDK globals — reading them at JSON-emit time made
+    // `researchers`/`trackedErrors` silently vanish from a cancelled-but-
+    // successful payload depending on who won the race.
+    const outcome = getLastResearcherOutcome();
+    const errorReport = getLastErrorReport();
+
     // Optionally persist the report to a file (opt-in via
     // PI_RESEARCH_REPORT_EXPORT_ENABLED). The SDK is a pure library and does not
     // write files; the CLI front-end does, mirroring the pi tool path.
@@ -636,8 +661,7 @@ export async function cmdResearch(args: ResearchArgs): Promise<number> {
       // (ISSUES-ANALYSIS-2026-07-09.md, Symptom 4): a caller reading only stdout/JSON
       // had no way to distinguish "thin report, little material out there" from "thin
       // report because most researchers died mid-run" without opening the log file.
-      const outcome = getLastResearcherOutcome();
-      const errorReport = getLastErrorReport();
+      // (outcome/errorReport were snapshotted right after the run resolved — see above.)
       toStdout(pretty({
         ok: true,
         depth,
@@ -719,11 +743,20 @@ export async function cmdKnowledge(queries: string[], json?: boolean): Promise<n
     await safeShutdown();
   }
 
+  // Same latch as cmdResearch's post-run check: the abort signal's checks inside
+  // searchKnowledge are point-in-time, so a Ctrl-C landing after the last one lets
+  // the search resolve normally — without this, an interrupted run raced onSignal's
+  // flushAndExit and could report ok:true / exit 0. The rationale comment above
+  // named exactly this failure; only the throwing half was previously handled.
+  if (cancellationRequested) {
+    exit = cancellationSignal ? exitCodeForSignal(cancellationSignal) : EXIT.CANCELLED;
+  }
+
   if (json) {
     // `ok: true` makes `ok` a reliable success/failure discriminant across every
     // knowledge JSON variant (disabled-store above, reportError's ok:false below,
     // and this success shape) — additive only, every existing field is unchanged.
-    toStdout(pretty({ ok: true, ...result }));
+    toStdout(pretty({ ok: true, ...(cancellationRequested ? { cancelled: true } : {}), ...result }));
   } else {
     toStdout((result.text.endsWith('\n') ? result.text : result.text + '\n'));
   }
@@ -738,6 +771,18 @@ async function cmdStatus(json?: boolean): Promise<number> {
   const det = await detectCredentials();
   const paths = resolvedConfigPaths();
   const cfg = getConfig(process.cwd(), 'cli');
+  // The stealth browser is installed by this package's `postinstall`
+  // (scripts/setup.cjs), which npm 11.19+ BLOCKS BY DEFAULT — it now warns
+  // "packages have install scripts not yet covered by allowScripts" and carries
+  // on, so the browser is simply absent on an otherwise successful install.
+  // Every other native artifact survives that (onnxruntime, sharp, esbuild and
+  // webgpu all ship prebuilt platform packages), which is exactly what makes
+  // this one worth reporting: nothing else fails, and without this the first
+  // symptom is a scrape falling back mid-run. A missing browser degrades
+  // capability rather than breaking the tool — the fetch path still serves most
+  // pages — so it is reported alongside `ready` rather than folded into it.
+  // isBrowserAvailable() is a resolve + existsSync; it never launches anything.
+  const browserInstalled = isBrowserAvailable();
   const summary = {
     package: '@lincoln504/pi-research',
     version: PKG_VERSION,
@@ -751,6 +796,14 @@ async function cmdStatus(json?: boolean): Promise<number> {
       modelFrom: det.modelFrom,
       problem: det.problem ?? null,
     },
+    browser: {
+      installed: browserInstalled,
+      // Same remedy the health check prints, so both surfaces name one command.
+      fix: browserInstalled ? null : 'npx camoufox-js fetch',
+      note: browserInstalled
+        ? null
+        : 'Stealth browser not installed — scraping falls back to plain fetch, which some sites block. npm 11.19+ blocks install scripts by default, which skips this package\'s postinstall.',
+    },
     knowledgeStoreMode: cfg.KNOWLEDGE_STORE_MODE,
     defaultDepth: cfg.DEFAULT_RESEARCH_DEPTH,
     paths,
@@ -764,6 +817,10 @@ async function cmdStatus(json?: boolean): Promise<number> {
   toStdout(`pi-research ${PKG_VERSION}\n`);
   toStdout(`ready: ${summary.ready ? 'yes' : 'no'}\n\n`);
   toStdout(configBlock(det, summary.ready ? undefined : '— fix the problem above, then re-run.') + '\n');
+  if (!summary.browser.installed) {
+    toStdout(`\nstealth browser: NOT INSTALLED — run: ${summary.browser.fix}\n`);
+    toStdout(`  ${summary.browser.note}\n`);
+  }
   toStdout(`\nknowledge store mode: ${cfg.KNOWLEDGE_STORE_MODE}   (default depth: ${cfg.DEFAULT_RESEARCH_DEPTH})\n`);
   return EXIT.OK;
 }
@@ -1032,7 +1089,17 @@ export async function reportError(err: unknown, what: string, json?: boolean): P
   // --json: emit a structured error on stdout so a machine consumer never has to
   // special-case plain-text stderr. Mirrors the { ok: true, ... } success shape.
   if (json) {
-    const payload: Record<string, unknown> = { ok: false, error: msg, exitCode };
+    // A cancellation reports itself as a cancellation, not as whatever component
+    // happened to notice the abort first. The internal message is genuinely
+    // misleading here — a Ctrl-C unwinding through the planner surfaces as
+    // "Coordinator failed: Request was aborted", so a consumer relaying `error`
+    // verbatim (which SKILL.md instructs agents to do) tells the user a component
+    // broke when they simply stopped the run. The plain-text branch below already
+    // refuses to say "failed" for a cancel; JSON said it anyway. The original
+    // wording is preserved under `cause` so nothing diagnostic is lost.
+    const payload: Record<string, unknown> = isCancellation
+      ? { ok: false, error: `pi-research ${what} cancelled.`, cause: msg, exitCode }
+      : { ok: false, error: msg, exitCode };
     // Machine-readable "this will succeed later" flag, so a consumer can back off
     // and retry without string-matching the human message. Gated on cancellation:
     // a Ctrl-C landing in the same window a queue-wait expires must never emit
@@ -1158,6 +1225,7 @@ COMMANDS
     --dry-run | --json           Plan only; JSON output.
 
   help, --help, -h               Show this help.
+  --version, -v                  Print the pi-research version.
 
 CONFIGURE
   Credentials are resolved in this order (first match wins):
@@ -1372,6 +1440,15 @@ export function parseArgs(argv: string[]): ParsedArgs {
       } else if (a === '--exclude-tools') {
         const v = takeOptionValue(rest, ++i, '--exclude-tools');
         excludeTools = v.split(',').map((s) => s.trim()).filter(Boolean);
+        // Unknown names fail fast: the merge downstream is a blind Set union, so a
+        // typo ("securty_search") silently excluded nothing while the user believed
+        // the tool was off for the whole (billed) run.
+        const unknown = excludeTools.filter((t) => !RESEARCH_TOOL_NAMES.includes(t));
+        if (unknown.length > 0) {
+          throw new UsageError(
+            `--exclude-tools: unknown tool name${unknown.length === 1 ? '' : 's'} ` +
+            `${unknown.map((t) => `"${t}"`).join(', ')}. Valid names: ${RESEARCH_TOOL_NAMES.join(', ')}.`);
+        }
         if (excludeTools.length === 0) excludeTools = undefined;
       } else if (a === '--initial-links') {
         // Consume until the next flag or end. Validate each entry: these are templated
@@ -1392,6 +1469,10 @@ export function parseArgs(argv: string[]): ParsedArgs {
           }
           j++;
         }
+        // Every other value-taking flag fails fast on a missing value; a bare
+        // `--initial-links` (immediately followed by another flag or end of args)
+        // silently proceeding with zero links was the one exception.
+        if (j === i + 1) throw new UsageError('--initial-links requires at least one URL.');
         i = j - 1;
       } else if (a === '--config') {
         configPath = takeOptionValue(rest, ++i, '--config');

package/src/config.ts

@@ -122,15 +122,6 @@ export const ConfigSchema = Type.Object({
    *  the model's real maxTokens at call time.
    *  Not exposed in TUI — controlled via PI_RESEARCH_SYNTHESIS_MAX_TOKENS env var. */
   SYNTHESIS_MAX_TOKENS: Type.Number({ minimum: 1024, maximum: 131072, default: 32768 }),
-  /** Max OUTPUT tokens per researcher LLM call (deep and quick sub-agent sessions).
-   *  Without a cap the session inherits the model's full catalog ceiling as the
-   *  per-request max_tokens — ~230k for large-context models — which providers that
-   *  budget-check max_tokens up front (OpenRouter 402s against remaining credits)
-   *  reject outright on low balances, even though the actual response would cost
-   *  cents. Default 16384: researcher turns are tool calls plus a cited report, far
-   *  below this. Clamped to the model's real ceiling at session build time.
-   *  Not exposed in TUI — controlled via PI_RESEARCH_RESEARCHER_MAX_TOKENS env var. */
-  RESEARCHER_MAX_TOKENS: Type.Number({ minimum: 1024, maximum: 131072, default: 16384 }),
   /** LLM Model override for researcher sub-agents and knowledge synthesis.
    *  Format: provider/model-id (e.g. google/gemini-2.0-flash-001) or just model-id.
    *  When set, this overrides ctx.model for researcher sub-agents (both deep and quick)
@@ -167,7 +158,8 @@ export const ConfigSchema = Type.Object({
   /**
    * Comma-separated list of research tools to DISABLE for every researcher in a run
    * (e.g. "scrape", or "youtube_transcript,stackexchange"). Valid tool names:
-   * search, scrape, security_search, stackexchange, youtube_transcript, grep.
+   * search, scrape, security_search, stackexchange, youtube_transcript, grep, read
+   * (RESEARCH_TOOL_NAMES in constants.ts is the canonical list).
    * Disable-only: the list is merged into the per-run excludeTools stream, so disabled
    * tools are both removed from each researcher's toolset AND named in the
    * coordinator/evaluator "DISABLED TOOLS" prompt section. Env-only
@@ -242,7 +234,6 @@ const USER_MIGRATION_KEYS = [
   'PI_RESEARCH_LLM_THINKING_LEVEL',
   'PI_RESEARCH_PLANNING_MAX_TOKENS',
   'PI_RESEARCH_SYNTHESIS_MAX_TOKENS',
-  'PI_RESEARCH_RESEARCHER_MAX_TOKENS',
   'PI_RESEARCH_MIGRATION_STRATEGY',
   'PI_RESEARCH_CONSOLE_LOG',
   'PI_RESEARCH_MODEL',
@@ -875,7 +866,6 @@ export function saveConfig(config: Config, scope: 'local' | 'user' = 'local', cw
     PI_RESEARCH_LLM_THINKING_LEVEL: config.LLM_THINKING_LEVEL,
     PI_RESEARCH_PLANNING_MAX_TOKENS: String(config.PLANNING_MAX_TOKENS),
     PI_RESEARCH_SYNTHESIS_MAX_TOKENS: String(config.SYNTHESIS_MAX_TOKENS),
-    PI_RESEARCH_RESEARCHER_MAX_TOKENS: String(config.RESEARCHER_MAX_TOKENS),
     PI_RESEARCH_MIGRATION_STRATEGY: config.MIGRATION_STRATEGY,
     PI_RESEARCH_CONSOLE_LOG: String(config.CONSOLE_LOG),
     ...(config.RESEARCH_MODEL ? { PI_RESEARCH_MODEL: config.RESEARCH_MODEL } : {}),
@@ -1106,7 +1096,6 @@ export function createConfig(env: Record<string, string | undefined>, processEnv
     LLM_THINKING_LEVEL: parseEnvEnum(e, 'PI_RESEARCH_LLM_THINKING_LEVEL', ['off', 'minimal', 'low', 'medium', 'high'] as const, DEFAULTS.LLM_THINKING_LEVEL),
     PLANNING_MAX_TOKENS: parseEnvNumber(e, 'PI_RESEARCH_PLANNING_MAX_TOKENS', DEFAULTS.PLANNING_MAX_TOKENS, 1024, 131072),
     SYNTHESIS_MAX_TOKENS: parseEnvNumber(e, 'PI_RESEARCH_SYNTHESIS_MAX_TOKENS', DEFAULTS.SYNTHESIS_MAX_TOKENS, 1024, 131072),
-    RESEARCHER_MAX_TOKENS: parseEnvNumber(e, 'PI_RESEARCH_RESEARCHER_MAX_TOKENS', DEFAULTS.RESEARCHER_MAX_TOKENS, 1024, 131072),
     MIGRATION_STRATEGY: parseEnvEnum(e, 'PI_RESEARCH_MIGRATION_STRATEGY', ['drop', 're-embed', 'backup'] as const, DEFAULTS.MIGRATION_STRATEGY),
     CONSOLE_LOG: parseEnvBool(e, 'PI_RESEARCH_CONSOLE_LOG', DEFAULTS.CONSOLE_LOG),
     RESEARCH_MODEL: parseEnvString(e, 'PI_RESEARCH_MODEL', DEFAULTS.RESEARCH_MODEL),
@@ -1226,7 +1215,9 @@ function parseEnvNumber(env: Record<string, string | undefined>, key: string, de
 }
 
 function parseEnvBool(env: Record<string, string | undefined>, key: string, def: boolean): boolean {
-  const v = env[key];
+  // Trim like parseEnvNumber does: file values arrive trimmed via parseDotEnv, but a
+  // real env var `PI_RESEARCH_X='true '` otherwise silently read false.
+  const v = env[key]?.trim();
   if (v === undefined || v === '') return def;
   // Strict by design: only the literal 'true' (any case) is truthy; every other value is false.
   // This is intentional and asserted in config.test.ts ('1'/'yes' → false) — do not loosen it.
@@ -1249,7 +1240,7 @@ function parseEnvEnum<T extends string>(
   allowed: readonly T[],
   def: T,
 ): T {
-  const raw = env[key];
+  const raw = env[key]?.trim();
   if (raw === undefined || raw === '') return def;
   if ((allowed as readonly string[]).includes(raw)) return raw as T;
   logger.warn(`[config] Invalid ${key}="${raw}" (expected one of: ${allowed.join(', ')}). Using default "${def}".`);

package/src/constants.ts

@@ -182,6 +182,19 @@ export const MAX_QUERIES_PER_RESEARCHER_LEVEL_3 = 20;
  */
 export const DEFAULT_EXCLUDED_TOOLS: readonly string[] = ['grep'];
 
+/**
+ * The complete set of excludable research tool names — the vocabulary
+ * `--exclude-tools` / `excludeTools` / PI_RESEARCH_DISABLED_TOOLS accept.
+ * Kept here (next to DEFAULT_EXCLUDED_TOOLS) so validation and the exclusion
+ * machinery cannot drift; the DISABLED_TOOLS doc in config.ts names the same set.
+ * `read` is a researcher tool too (local file reads) — excluding it is a
+ * legitimate hardening move, and omitting it from this list broke exactly that
+ * on the CLI when validation was introduced.
+ */
+export const RESEARCH_TOOL_NAMES: readonly string[] = [
+  'search', 'scrape', 'security_search', 'stackexchange', 'youtube_transcript', 'grep', 'read',
+];
+
 /**
  * Resolve the effective researcher exclusion list.
  *

package/src/core/service-registry.ts

@@ -178,10 +178,26 @@ export class ServiceContainer {
     options: ServiceContainerOptions = {}
   ): Promise<void> {
     const mergedOptions = { ...this.defaultOptions, ...options, allowOverwrite: true };
-    
+
     // Dispose existing service if present
-    if (this.services.has(name)) {
-      const registration = this.services.get(name)!;
+    const registration = this.services.get(name);
+    if (registration) {
+      // Join an already-in-flight clear()/replace()/disposeAll() on this
+      // registration before touching its instance — the same guard those paths
+      // use on each other. Without it, a concurrent teardown and this call both
+      // dispose the SAME instance, and register() below then swaps the whole
+      // registration object out from under the in-flight one, orphaning any
+      // instance it constructs.
+      // while(), not if(): a newer disposal can begin while we are awaiting this
+      // one, exactly as get() documents for the same field.
+      while (registration.disposalPromise) {
+        await registration.disposalPromise.catch(() => { /* disposal errors are logged by clear()/replace() */ });
+      }
+      // Settle an in-flight initialization too, so we never discard a service
+      // that is still being built — mirrors replace().
+      if (registration.initializationPromise) {
+        await registration.initializationPromise.catch(() => { /* failed init cleaned up after itself */ });
+      }
       if (registration.instance && registration.instance.dispose) {
         try {
           await registration.instance.dispose();

package/src/infrastructure/browser/config.ts

@@ -31,15 +31,40 @@ 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.
+ *
+ * CAVEAT, deliberate: the pinned camoufox-js (0.10.x — see
+ * thread-worker-browser.ts for why it cannot move yet) hardcodes
+ * `userCacheDir("camoufox")` and honours NEITHER variable, so on the shipped
+ * pin a custom location still only relocates lookup and the underlying bug
+ * remains. This plumbing is correct and inert rather than wrong: it starts
+ * working the moment the pin can advance, and costs nothing until then. Until
+ * that happens, treat a custom browser directory as unsupported.
+ */
+function getCustomCamoufoxDir(): string | undefined {
+    return process.env['CAMOUFOX_INSTALL_DIR'] || process.env['PLAYWRIGHT_BROWSERS_PATH'] || undefined;
+}
+
 /**
  * Get the camoufox binary cache directory.
- * Uses PLAYWRIGHT_BROWSERS_PATH if set, otherwise the standard user cache location
+ * Uses the custom location above if set, otherwise the standard user cache location
  * that camoufox uses by default (~/.cache/camoufox on Linux).
  * We do NOT override HOME — that trick was unreliable and caused install/runtime mismatches.
  */
 export function getBrowserCacheDir(): string {
-    if (process.env['PLAYWRIGHT_BROWSERS_PATH']) {
-        return process.env['PLAYWRIGHT_BROWSERS_PATH'];
+    const custom = getCustomCamoufoxDir();
+    if (custom) {
+        return custom;
     }
     // Mirror getCamoufoxBinaryPath() so both functions agree on the cache location
     const osPlatform = platform();
@@ -109,11 +134,17 @@ export function getBrowserProfileDir(config?: Config): string {
  */
 export function getBrowserEnv(config?: Config): NodeJS.ProcessEnv {
     const env: NodeJS.ProcessEnv = { ...process.env };
-    const customPath = process.env['PLAYWRIGHT_BROWSERS_PATH'];
+    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'];
     }
     // 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 —
@@ -164,7 +195,7 @@ export function ensureBrowserCacheDir(): string {
  * Matches camoufox-js's own resolution logic.
  */
 export function getCamoufoxBinaryPath(): string {
-    const customPath = process.env['PLAYWRIGHT_BROWSERS_PATH'];
+    const customPath = getCustomCamoufoxDir();
     if (customPath) {
         return customPath;
     }

package/src/infrastructure/browser/task-execution-service.ts

@@ -136,9 +136,19 @@ async function isRegisteredLeaderAlive(container: ServiceContainer): Promise<boo
     return result;
 }
 
-/** Test seam: drop the coalesced liveness probe. */
-export function _resetLeaderLivenessProbeForTests(): void {
+/**
+ * Test seam: drop BOTH module-level globals that survive between tests — the
+ * coalesced liveness probe (1s window) and the restart cooldown (10s window).
+ *
+ * Both are far longer than a test file's runtime, so a test that reaches
+ * restartSchedulerWithHerdGuard leaves state that silently short-circuits the
+ * next one: isRegisteredLeaderAliveUncached / forceSchedulerRestart simply are
+ * not re-invoked. Today nothing observes that only because the one test that
+ * reaches this path happens to run last — ordering, not a guarantee.
+ */
+export function _resetTaskExecutionGlobalsForTests(): void {
     leaderLivenessProbe = null;
+    lastRestartTime = 0;
 }
 
 /**

package/src/infrastructure/browser/thread-worker-browser.ts

@@ -134,29 +134,45 @@ export async function initBrowser(): Promise<void> {
         // (consumers install without our lockfile, so a floating range resolves
         // to a newer, broken version):
         //
-        //   • camoufox-js  ^0.10.2  → fetches camoufox Firefox 135 / beta.24, the
-        //     NEWEST camoufox with binaries for every OS we support (Linux x64/
-        //     arm64, macOS x64/arm64, Windows x64). FF146/FF150 dropped the
-        //     Windows build entirely, so the 0.11.x line breaks Windows installs.
+        //   • camoufox-js  ^0.10.2  → the two ORIGINAL reasons for this pin have
+        //     both lapsed (camoufox restored Windows assets in v152.0.4-beta.26,
+        //     2026-07-16; and impit's `only-allow pnpm` guard existed only in
+        //     0.13.1/0.14.0), but a THIRD, worse one replaced them. 0.12.0
+        //     requires `better-sqlite3 ^13.0.1`, and better-sqlite3 13 DROPPED
+        //     PREBUILT BINARIES: 12.x installs via `prebuild-install || node-gyp
+        //     rebuild`, 13.x has no install script at all, so npm falls back to
+        //     auto-running `node-gyp rebuild` for its binding.gyp and every
+        //     install needs a full C++ toolchain. Measured: `npm ci` fails
+        //     outright on the Windows CI runner ("could not find a version of
+        //     Visual Studio 2017 or newer"), which is most Windows consumers.
+        //     Upgrading again means checking better-sqlite3 first, not camoufox.
         //   • playwright-core  1.60.0 (exact) → playwright-core and the camoufox
         //     binary are one matched Juggler-protocol pair. 1.61 added a
-        //     viewport.isMobile field the FF135 build REJECTS ("property
+        //     viewport.isMobile field the build REJECTS ("property
         //     viewport.isMobile not described in this scheme"), failing every
-        //     launch below. 1.60.0 is the newest playwright the FF135 Juggler
-        //     accepts.
+        //     launch below. Corroborated upstream: camoufox-js 0.12.0 declares
+        //     `peerDependencies: playwright-core "<1.61.0"`, the same bound this
+        //     pin has held by hand.
         //   • impit  0.13.0 (exact, a direct dep though only camoufox-js uses it)
-        //     → impit 0.13.1/0.14.0 shipped a `preinstall: npx only-allow pnpm`
-        //     guard (an upstream mistake, fixed in 0.14.1+) that hard-fails
-        //     `npm install -g`. Within camoufox-js's ^0.13.0 range 0.13.0 is the
-        //     only guard-free version; a direct-dep pin is the ONLY way to force
-        //     it for consumers (npm `overrides` don't propagate to installers of
-        //     a published package).
+        //     → camoufox-js 0.10.2 requires `impit ^0.13.0`, and within that range
+        //     0.13.0 is the only version free of the `preinstall: npx only-allow
+        //     pnpm` guard (an upstream mistake in 0.13.1/0.14.0, dropped again in
+        //     0.14.1) that hard-fails `npm install -g`. The exact pin is also the
+        //     ONLY way to force a version for consumers, since npm `overrides`
+        //     don't propagate to installers of a published package.
         //
-        // Removal: upgrade all three together when camoufox ships stable
-        // cross-platform (incl. Windows) FF150 binaries — bumping camoufox-js to
-        // ≥0.11.1 also drops the impit pin (0.11.1 requires the fixed impit
-        // ^0.14.1) and needs playwright re-pinned to the new build's Juggler.
-        // Always re-verify a real headless run on Linux/macOS/Windows after.
+        // What is NOT pinned: the browser BINARY. `camoufox-js fetch` takes no
+        // version argument — it walks the GitHub releases newest-first and takes
+        // the first non-prerelease one with an asset for this OS/arch. A consumer
+        // therefore gets whatever camoufox published most recently, whichever
+        // camoufox-js they have, and a future release could break launches with no
+        // change on our side. Both the current newest (v152.0.4-beta.28, Firefox
+        // 152) and the older v135.0.1-beta.24 an existing cache may hold were
+        // verified launching and driving under playwright-core 1.60.0.
+        //
+        // Always re-verify a REAL headless run after touching any of this: the
+        // unit and integration suites mock the browser, so a Juggler mismatch
+        // reaches production with a fully green suite.
         let CamoufoxModule: any;
         try {
           CamoufoxModule = await import('camoufox-js');

package/src/infrastructure/browser/thread-worker.mjs

@@ -99,7 +99,10 @@ var init_log_utils = __esm({
       `${B_LEFT}(sk-[A-Za-z0-9_-]{16,}|gh[posru]_[A-Za-z0-9]{16,}|github_pat_[A-Za-z0-9_]{20,}|AKIA[0-9A-Z]{16}|xox[baprs]-[A-Za-z0-9-]{10,})${B_RIGHT}`,
       "g"
     );
-    JWT_PATTERN = new RegExp(`${B_LEFT}eyJ[A-Za-z0-9_-]+\\.[A-Za-z0-9_-]+\\.[A-Za-z0-9_-]+`, "g");
+    JWT_PATTERN = new RegExp(
+      `${B_LEFT}eyJ[A-Za-z0-9_-]{1,1024}\\.[A-Za-z0-9_-]{1,8192}\\.[A-Za-z0-9_-]{1,4096}`,
+      "g"
+    );
     BASIC_AUTH_PATTERN = new RegExp(`${B_LEFT}Basic\\s+[A-Za-z0-9+/]{16,}={0,2}`, "gi");
     BEARER_AUTH_PATTERN = new RegExp(`${B_LEFT}Bearer\\s+[A-Za-z0-9._~+/-]+=*`, "gi");
     PROVIDER_TOKEN_PATTERN = new RegExp(
@@ -1509,6 +1512,7 @@ var scraper_utils_exports = {};
 __export(scraper_utils_exports, {
   createJsMarkdownConverter: () => createJsMarkdownConverter,
   createNativeMarkdownConverter: () => createNativeMarkdownConverter,
+  disposeSsrfSafeFetcher: () => disposeSsrfSafeFetcher,
   extractDomain: () => extractDomain,
   formatErrorWithCause: () => formatErrorWithCause,
   getRandomUserAgent: () => getRandomUserAgent,
@@ -1644,19 +1648,33 @@ function isSsrfBlockError(error) {
   }
   return false;
 }
-async function getSsrfSafeFetcher() {
-  if (cachedSsrfFetcher !== void 0) return cachedSsrfFetcher;
+function getSsrfSafeFetcher() {
+  cachedSsrfFetcher ??= (async () => {
+    try {
+      const { Agent, fetch: undiciFetch } = await import("undici");
+      return {
+        fetch: undiciFetch,
+        dispatcher: new Agent({ connect: { lookup: ssrfSafeLookup } })
+      };
+    } catch (e) {
+      logger.warn(`[Scrapers] undici unavailable; connect-time SSRF pinning disabled (request-time validation still active): ${e instanceof Error ? e.message : String(e)}`);
+      return null;
+    }
+  })();
+  return cachedSsrfFetcher;
+}
+async function disposeSsrfSafeFetcher() {
+  const pending = cachedSsrfFetcher;
+  cachedSsrfFetcher = void 0;
+  if (pending === void 0) return;
+  const cached = await pending.catch(() => null);
+  const closable = cached?.dispatcher;
+  if (!closable?.close) return;
   try {
-    const { Agent, fetch: undiciFetch } = await import("undici");
-    cachedSsrfFetcher = {
-      fetch: undiciFetch,
-      dispatcher: new Agent({ connect: { lookup: ssrfSafeLookup } })
-    };
+    await closable.close();
   } catch (e) {
-    logger.warn(`[Scrapers] undici unavailable; connect-time SSRF pinning disabled (request-time validation still active): ${e instanceof Error ? e.message : String(e)}`);
-    cachedSsrfFetcher = null;
+    logger.debug(`[Scrapers] Error closing SSRF dispatcher: ${e instanceof Error ? e.message : String(e)}`);
   }
-  return cachedSsrfFetcher;
 }
 function formatErrorWithCause(err) {
   try {
@@ -2544,15 +2562,6 @@ var ConfigSchema = Type.Object({
    *  the model's real maxTokens at call time.
    *  Not exposed in TUI — controlled via PI_RESEARCH_SYNTHESIS_MAX_TOKENS env var. */
   SYNTHESIS_MAX_TOKENS: Type.Number({ minimum: 1024, maximum: 131072, default: 32768 }),
-  /** Max OUTPUT tokens per researcher LLM call (deep and quick sub-agent sessions).
-   *  Without a cap the session inherits the model's full catalog ceiling as the
-   *  per-request max_tokens — ~230k for large-context models — which providers that
-   *  budget-check max_tokens up front (OpenRouter 402s against remaining credits)
-   *  reject outright on low balances, even though the actual response would cost
-   *  cents. Default 16384: researcher turns are tool calls plus a cited report, far
-   *  below this. Clamped to the model's real ceiling at session build time.
-   *  Not exposed in TUI — controlled via PI_RESEARCH_RESEARCHER_MAX_TOKENS env var. */
-  RESEARCHER_MAX_TOKENS: Type.Number({ minimum: 1024, maximum: 131072, default: 16384 }),
   /** LLM Model override for researcher sub-agents and knowledge synthesis.
    *  Format: provider/model-id (e.g. google/gemini-2.0-flash-001) or just model-id.
    *  When set, this overrides ctx.model for researcher sub-agents (both deep and quick)
@@ -2589,7 +2598,8 @@ var ConfigSchema = Type.Object({
   /**
    * Comma-separated list of research tools to DISABLE for every researcher in a run
    * (e.g. "scrape", or "youtube_transcript,stackexchange"). Valid tool names:
-   * search, scrape, security_search, stackexchange, youtube_transcript, grep.
+   * search, scrape, security_search, stackexchange, youtube_transcript, grep, read
+   * (RESEARCH_TOOL_NAMES in constants.ts is the canonical list).
    * Disable-only: the list is merged into the per-run excludeTools stream, so disabled
    * tools are both removed from each researcher's toolset AND named in the
    * coordinator/evaluator "DISABLED TOOLS" prompt section. Env-only

package/src/infrastructure/gpu-resource-service.ts

@@ -27,7 +27,21 @@ export class GPUResourceService implements IGPUResourceService {
   lifecycle = ServiceLifecycle.UNINITIALIZED;
 
   private processLifecycle: IProcessLifecycle | null = null;
-  private gpuLockStaleThresholdMs: number = 1000 * 60 * 5; // 5 minutes default
+  /**
+   * Backstop for a holder that is alive but wedged. Step 3 already reclaims from
+   * *dead* owners via PID+startTime liveness, so this only ever fires against a
+   * process we just proved is running — which makes it a lock STEAL, and the
+   * threshold must therefore exceed the longest legitimate hold.
+   *
+   * It previously did not: at 5 minutes it exactly equalled the default
+   * EMBEDDING_MODEL_INIT_TIMEOUT_MS (300000, schema max 600000), and the
+   * embedder holds this lock across the whole model download + pipeline load.
+   * A first-time HuggingFace fetch running near its own permitted budget would
+   * have the GPU lock taken out from under it, admitting exactly the concurrent
+   * WebGPU/Dawn init this lock exists to prevent. Keep this strictly above that
+   * schema maximum.
+   */
+  private gpuLockStaleThresholdMs: number = 1000 * 60 * 15; // 15 min > EMBEDDING_MODEL_INIT_TIMEOUT_MS max (10 min)
 
   constructor(options?: GPUResourceServiceOptions) {
     if (options) {