@lincoln504/pi-research 1.3.11 → 1.3.12

package/dist/cli.mjs

@@ -269,7 +269,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(
@@ -1158,8 +1161,16 @@ var init_service_registry = __esm({
        */
       async registerAndReplace(name, factory, options = {}) {
         const mergedOptions = { ...this.defaultOptions, ...options, allowOverwrite: true };
-        if (this.services.has(name)) {
-          const registration = this.services.get(name);
+        const registration = this.services.get(name);
+        if (registration) {
+          while (registration.disposalPromise) {
+            await registration.disposalPromise.catch(() => {
+            });
+          }
+          if (registration.initializationPromise) {
+            await registration.initializationPromise.catch(() => {
+            });
+          }
           if (registration.instance && registration.instance.dispose) {
             try {
               await registration.instance.dispose();
@@ -6985,7 +6996,17 @@ async function loadModelOnCPU(model, initializationTimeoutMs, useCache) {
         interOpNumThreads: 1
       }
     });
-    return await withTimeout3(pipelinePromise, initializationTimeoutMs, "CPU fallback model load timed out");
+    let timedOut = true;
+    try {
+      const p = await withTimeout3(pipelinePromise, initializationTimeoutMs, "CPU fallback model load timed out");
+      timedOut = false;
+      return p;
+    } finally {
+      if (timedOut) {
+        pipelinePromise.then((late) => late.dispose?.()).catch(() => {
+        });
+      }
+    }
   });
   return loadedPipeline;
 }
@@ -9182,6 +9203,7 @@ function formatQueriesBlock(queries) {
 }
 function showKnowledgeSearchWidget(ctx) {
   if (ctx.mode !== "tui" || !ctx.hasUI) return;
+  knowledgeWidgetRefCount++;
   try {
     const panelFactory = createKnowledgeSearchPanel();
     ctx.ui.setWidget(KNOWLEDGE_WIDGET_ID, panelFactory, { placement: "aboveEditor" });
@@ -9191,6 +9213,8 @@ function showKnowledgeSearchWidget(ctx) {
 }
 function hideKnowledgeSearchWidget(ctx) {
   if (ctx.mode !== "tui" || !ctx.hasUI) return;
+  knowledgeWidgetRefCount = Math.max(0, knowledgeWidgetRefCount - 1);
+  if (knowledgeWidgetRefCount > 0) return;
   try {
     ctx.ui.setWidget(KNOWLEDGE_WIDGET_ID, void 0, { placement: "aboveEditor" });
   } catch (err) {
@@ -9670,7 +9694,7 @@ function createResearchKnowledgeSearchTool(iface) {
     }
   };
 }
-var ResearchKnowledgeSearchParams, MAX_REFERENCE_CHARS, MAX_DOCUMENTS, MAX_CANDIDATES, TRIAGE_DESCRIPTION_MAX_CHARS, TRIAGE_MAX_TOKENS, KNOWLEDGE_WIDGET_ID, RESEARCH_KNOWLEDGE_MISS_STRING, RESEARCH_KNOWLEDGE_MAYBE_STRING, KNOWLEDGE_SYNTHESIS_MAX_ATTEMPTS, KNOWLEDGE_SYNTHESIS_RETRY_BASE_MS;
+var ResearchKnowledgeSearchParams, MAX_REFERENCE_CHARS, MAX_DOCUMENTS, MAX_CANDIDATES, TRIAGE_DESCRIPTION_MAX_CHARS, TRIAGE_MAX_TOKENS, KNOWLEDGE_WIDGET_ID, knowledgeWidgetRefCount, RESEARCH_KNOWLEDGE_MISS_STRING, RESEARCH_KNOWLEDGE_MAYBE_STRING, KNOWLEDGE_SYNTHESIS_MAX_ATTEMPTS, KNOWLEDGE_SYNTHESIS_RETRY_BASE_MS;
 var init_research_knowledge_search = __esm({
   "src/tools/research-knowledge-search.ts"() {
     "use strict";
@@ -9705,6 +9729,7 @@ var init_research_knowledge_search = __esm({
     TRIAGE_DESCRIPTION_MAX_CHARS = 600;
     TRIAGE_MAX_TOKENS = 2048;
     KNOWLEDGE_WIDGET_ID = "pi-research-knowledge-search";
+    knowledgeWidgetRefCount = 0;
     RESEARCH_KNOWLEDGE_MISS_STRING = "No results found. Live research can get the info.";
     RESEARCH_KNOWLEDGE_MAYBE_STRING = "Partial results found in knowledge store. Live research can fill gaps.";
     KNOWLEDGE_SYNTHESIS_MAX_ATTEMPTS = 3;
@@ -11460,9 +11485,13 @@ import { platform, homedir as homedir2 } from "node:os";
 function getWindowsCamoufoxDir() {
   return join7(homedir2(), "AppData", "Local", "camoufox", "camoufox", "Cache");
 }
+function getCustomCamoufoxDir() {
+  return process.env["CAMOUFOX_INSTALL_DIR"] || process.env["PLAYWRIGHT_BROWSERS_PATH"] || void 0;
+}
 function getBrowserCacheDir() {
-  if (process.env["PLAYWRIGHT_BROWSERS_PATH"]) {
-    return process.env["PLAYWRIGHT_BROWSERS_PATH"];
+  const custom = getCustomCamoufoxDir();
+  if (custom) {
+    return custom;
   }
   const osPlatform = platform();
   if (osPlatform === "win32") {
@@ -11493,11 +11522,13 @@ function getBrowserProfileDir(config) {
 }
 function getBrowserEnv(config) {
   const env = { ...process.env };
-  const customPath = process.env["PLAYWRIGHT_BROWSERS_PATH"];
+  const customPath = getCustomCamoufoxDir();
   if (customPath) {
     env["PLAYWRIGHT_BROWSERS_PATH"] = customPath;
+    env["CAMOUFOX_INSTALL_DIR"] = customPath;
   } else {
     delete env["PLAYWRIGHT_BROWSERS_PATH"];
+    delete env["CAMOUFOX_INSTALL_DIR"];
   }
   if (!env["PI_RESEARCH_LOG_FILE"]) {
     const logFilePath = getLogger().getLogFilePath();
@@ -11526,7 +11557,7 @@ function ensureBrowserCacheDir() {
   return cacheDir;
 }
 function getCamoufoxBinaryPath() {
-  const customPath = process.env["PLAYWRIGHT_BROWSERS_PATH"];
+  const customPath = getCustomCamoufoxDir();
   if (customPath) {
     return customPath;
   }
@@ -14304,8 +14335,22 @@ var GPUResourceService = class {
   name = ServiceNames.GPU_RESOURCE_SERVICE;
   lifecycle = "uninitialized" /* UNINITIALIZED */;
   processLifecycle = null;
-  gpuLockStaleThresholdMs = 1e3 * 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.
+   */
+  gpuLockStaleThresholdMs = 1e3 * 60 * 15;
+  // 15 min > EMBEDDING_MODEL_INIT_TIMEOUT_MS max (10 min)
   constructor(options) {
     if (options) {
       this.processLifecycle = options.processLifecycle;
@@ -17115,19 +17160,33 @@ function isSsrfBlockError(error) {
   return false;
 }
 var cachedSsrfFetcher = void 0;
-async function getSsrfSafeFetcher() {
-  if (cachedSsrfFetcher !== void 0) return cachedSsrfFetcher;
+function getSsrfSafeFetcher() {
+  cachedSsrfFetcher ??= (async () => {
+    try {
+      const { Agent: Agent2, fetch: undiciFetch } = await import("undici");
+      return {
+        fetch: undiciFetch,
+        dispatcher: new Agent2({ 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: Agent2, fetch: undiciFetch } = await import("undici");
-    cachedSsrfFetcher = {
-      fetch: undiciFetch,
-      dispatcher: new Agent2({ 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 {
@@ -17986,7 +18045,6 @@ import { Value as Value7 } from "typebox/value";
 // src/security/nvd-client.ts
 init_retry_utils();
 init_circuit_breaker();
-init_safe_unref();
 init_metrics();
 init_http_body();
 
@@ -18049,7 +18107,6 @@ var NVDRateLimiter = class {
           signal?.removeEventListener("abort", onAbort);
           resolve9();
         }, waitTime);
-        safeUnref(timeoutId);
         const onAbort = () => {
           clearTimeout(timeoutId);
           reject(Object.assign(new Error("NVD search aborted"), { name: "AbortError" }));
@@ -18271,6 +18328,7 @@ async function fetchPaginated(term, options, maxResults, severityVersion, admitE
   const signal = options?.signal;
   let startIndex = 0;
   let totalPagesFetched = 0;
+  let seekedToNewest = false;
   while (totalPagesFetched < maxPages && allVulnerabilities.length < maxResults) {
     if (signal?.aborted) break;
     const url = buildURL(term, options, pageSize, startIndex, severityVersion);
@@ -18291,9 +18349,17 @@ async function fetchPaginated(term, options, maxResults, severityVersion, admitE
       break;
     }
     metrics.increment("nvd_cache_hits_total", 1);
-    allVulnerabilities.push(...admitted);
     const responseData = data;
-    if (responseData?.["totalResults"] !== void 0 && typeof responseData["totalResults"] === "number" && startIndex + pageSize >= responseData["totalResults"]) {
+    const reportedTotal = typeof responseData?.["totalResults"] === "number" ? responseData["totalResults"] : void 0;
+    if (!seekedToNewest && startIndex === 0 && reportedTotal !== void 0 && reportedTotal > maxResults) {
+      seekedToNewest = true;
+      startIndex = reportedTotal - maxResults;
+      allVulnerabilities.length = 0;
+      totalPagesFetched++;
+      continue;
+    }
+    allVulnerabilities.push(...admitted);
+    if (reportedTotal !== void 0 && startIndex + pageSize >= reportedTotal) {
       break;
     }
     startIndex += pageSize;
@@ -18301,6 +18367,14 @@ async function fetchPaginated(term, options, maxResults, severityVersion, admitE
   }
   metrics.increment("nvd_pagination_requests_total", totalPagesFetched);
   metrics.observe("nvd_pagination_pages_fetched", totalPagesFetched);
+  allVulnerabilities.sort((a, b) => {
+    const ta = a.published ? Date.parse(a.published) : NaN;
+    const tb = b.published ? Date.parse(b.published) : NaN;
+    if (Number.isNaN(ta) && Number.isNaN(tb)) return 0;
+    if (Number.isNaN(ta)) return 1;
+    if (Number.isNaN(tb)) return -1;
+    return tb - ta;
+  });
   return allVulnerabilities.slice(0, maxResults);
 }
 function shouldSupplementWithV2(options) {
@@ -19311,7 +19385,14 @@ async function searchOSV(terms, options) {
         uniqueVulns.set(vuln.id, vuln);
       }
     }
-    vulnerabilities.push(...Array.from(uniqueVulns.values()));
+    vulnerabilities.push(...Array.from(uniqueVulns.values()).sort((a, b) => {
+      const ta = a.published ? Date.parse(a.published) : NaN;
+      const tb = b.published ? Date.parse(b.published) : NaN;
+      if (Number.isNaN(ta) && Number.isNaN(tb)) return 0;
+      if (Number.isNaN(ta)) return 1;
+      if (Number.isNaN(tb)) return -1;
+      return tb - ta;
+    }));
     if (failures.length > 0 && failures.length === terms.length) {
       throw new Error(`All OSV lookups failed: ${failures.join("; ")}`);
     }
@@ -23158,6 +23239,17 @@ var ResearchOrchestrationService = class {
     const { ctx, query, depth = 0, observer, onUpdate, sessionId, researchId, config, excludeTools } = options;
     const researchConfig = config || getConfig(ctx.cwd);
     const configDisabledTools = researchConfig.DISABLED_TOOLS ? researchConfig.DISABLED_TOOLS.split(",").map((s) => s.trim()).filter(Boolean) : [];
+    for (const [surface, names] of [
+      ["excludeTools", excludeTools ?? []],
+      ["PI_RESEARCH_DISABLED_TOOLS", configDisabledTools]
+    ]) {
+      const unknown = names.filter((t) => !RESEARCH_TOOL_NAMES.includes(t));
+      if (unknown.length > 0) {
+        logger.warn(
+          `[ResearchOrchestrationService] ${surface}: ignoring unknown tool name${unknown.length === 1 ? "" : "s"} ${unknown.map((t) => `"${t}"`).join(", ")} \u2014 these exclude nothing. Valid names: ${RESEARCH_TOOL_NAMES.join(", ")}.`
+        );
+      }
+    }
     const mergedExcludeTools = resolveExcludedTools(excludeTools, configDisabledTools);
     const selectedModel = await this.resolveResearchModel(options);
     logger.info(`[ResearchOrchestrationService] Using model: ${selectedModel.provider}/${selectedModel.id}`);
@@ -24576,6 +24668,12 @@ async function _doShutdown() {
     logger.error("[SDK] Error clearing session state:", err);
     errors.push(err instanceof Error ? err : new Error(String(err)));
   }
+  try {
+    await disposeSsrfSafeFetcher();
+  } catch (err) {
+    logger.error("[SDK] Error disposing SSRF fetcher:", err);
+    errors.push(err instanceof Error ? err : new Error(String(err)));
+  }
   if (globalContainer) {
     try {
       await disposeCoreServices(globalContainer);
@@ -25298,6 +25396,7 @@ async function cmdStatus(json) {
   const det = await detectCredentials();
   const paths = resolvedConfigPaths();
   const cfg = getConfig(process.cwd(), "cli");
+  const browserInstalled = isBrowserAvailable();
   const summary = {
     package: "@lincoln504/pi-research",
     version: PKG_VERSION,
@@ -25311,6 +25410,12 @@ async function cmdStatus(json) {
       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 \u2014 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
@@ -25325,6 +25430,13 @@ async function cmdStatus(json) {
 
 `);
   toStdout(configBlock(det, summary.ready ? void 0 : "\u2014 fix the problem above, then re-run.") + "\n");
+  if (!summary.browser.installed) {
+    toStdout(`
+stealth browser: NOT INSTALLED \u2014 run: ${summary.browser.fix}
+`);
+    toStdout(`  ${summary.browser.note}
+`);
+  }
   toStdout(`
 knowledge store mode: ${cfg.KNOWLEDGE_STORE_MODE}   (default depth: ${cfg.DEFAULT_RESEARCH_DEPTH})
 `);
@@ -25523,7 +25635,7 @@ async function reportError(err, what, json) {
   const isRateLimit = !isCancellation && (lower.includes("429") || lower.includes("rate limit") || lower.includes("too many requests"));
   const exitCode = isCancellation ? cancellationSignal ? exitCodeForSignal(cancellationSignal) : EXIT.CANCELLED : isCapacity ? EXIT.TEMPFAIL : isConfigError && !isRateLimit ? EXIT.CONFIG : EXIT.SOFTWARE;
   if (json) {
-    const payload = { ok: false, error: msg2, exitCode };
+    const payload = isCancellation ? { ok: false, error: `pi-research ${what} cancelled.`, cause: msg2, exitCode } : { ok: false, error: msg2, exitCode };
     if ((isCapacity || isRateLimit) && !isCancellation) payload["retryable"] = true;
     if (isCancellation) payload["cancelled"] = true;
     if (process.env["PI_RESEARCH_DEBUG"] === "true" && err instanceof Error && err.stack) {

package/dist/prompts/system-coordinator.md

@@ -36,7 +36,7 @@ Before splitting the query into researchers, pin down its scope — exactly what
 
 1. **Plan ONLY Round 1**: Split the query into distinct sub-topics, all inside the scope above, each assigned to a researcher. **Do NOT plan multiple rounds in advance** — additional rounds are only delegated reactively when Round 1 findings reveal gaps.
 2. **Assign Goals**: Each researcher gets a focused goal covering a specific angle or time period.
-3. **Temporal Awareness**: Lead with the current month and year shown above. Generate time-sensitive queries using that exact month and year (e.g., append the current year and, where relevant, the current month; "latest", "current status"). Never anchor queries to an older year (e.g. 2024 or 2025) unless the user explicitly asks about the past. Research MUST be grounded in the present month and year.
+3. **Temporal Awareness**: Lead with the current month and year shown above. Generate time-sensitive queries using that exact month and year (e.g., append the current year and, where relevant, the current month; "latest", "current status"). Never anchor queries to an older year than the one shown above unless the user explicitly asks about the past. Research MUST be grounded in the present month and year.
 4. **Query Planning**: For EACH researcher, generate targeted, specific queries within the budget. Fill the budget when the topic is broad enough to warrant it, but don't pad queries for a narrow topic. Each round is planned independently — make Round 1 count.
 5. **YouTube Discovery**: For roughly **one in {{youtube_query_every_n}}** of each researcher's queries, append the word `youtube` to the query text (e.g. `"<topic> explained youtube"`). DuckDuckGo rarely surfaces YouTube on its own, and YouTube links let researchers read video transcripts. Skip this only when the topic is clearly unsuited to video (e.g. a single numeric lookup).
 6. **Seed Search Burst**: All queries across all researchers are combined into a single pre-search pass that seeds the global link pool.

package/dist/prompts/system-lead-evaluator.md

@@ -74,7 +74,7 @@ Use unique, targeted queries for any new researchers.
 - **CRITICAL — Queries are mandatory**: Every researcher MUST have at least one query. Never plan a researcher without queries. Researchers receive ONLY the search results you delegate to them.
 - **Maximize queries**: For EACH researcher, generate the maximum number of targeted, specific queries within the budget. Do not plan fewer than needed — fill the budget. Queries should target primary sources and authoritative evidence.
 - **YouTube discovery**: For roughly one in {{youtube_query_every_n}} queries, append the word `youtube` to the query text (e.g. `"<topic> analysis youtube"`). DuckDuckGo rarely surfaces YouTube on its own, and YouTube links let researchers read video transcripts. Skip only when the gap is clearly unsuited to video.
-- **Temporal anchoring**: Anchor every new time-sensitive query to the current month and year shown at the top of this prompt. Use that exact year (and month where relevant); never default to an older year such as 2024 or 2025 unless the user explicitly asks about the past.
+- **Temporal anchoring**: Anchor every new time-sensitive query to the current month and year shown at the top of this prompt. Use that exact year (and month where relevant); never default to an older year than the one shown there unless the user explicitly asks about the past.
 - **Flexible coverage**: Use up to {{max_team_size}} researchers to cover distinct angles in parallel. Scale based on research gaps — a single well-targeted researcher is often sufficient for focused gaps.
 - **Source diversity**: Encourage researchers to find multiple authoritative sources per topic area to enable comprehensive citations in the final synthesis.
 

package/dist/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 {

package/docs/ARCHITECTURE.md

@@ -301,24 +301,61 @@ Worker pool over direct browser — browser processes are isolated in workers so
 in one cannot affect the orchestrator or other sessions.
 
 Pinned browser stack — `playwright-core` and `impit` are pinned to exact versions and
-`camoufox-js` to its `0.10.x` line (`^0.10.2`, which excludes the `0.11.x` alpha); the
-three are coupled and upgraded together, because each floating range broke fresh consumer
-installs that our lockfile masked. camoufox-js `0.10.2` fetches Firefox
-135/beta.24, the newest camoufox with binaries for every supported OS (later builds
-dropped Windows). playwright-core `1.60.0` is the newest the FF135 Juggler protocol
-accepts (1.61 rejects it and fails every launch). impit `0.13.0` avoids the
-`only-allow pnpm` preinstall guard that impit 0.13.1/0.14.0 shipped, which fails
-`npm install -g`; a direct-dependency pin is required because npm `overrides` do not
-propagate to consumers. Will upgrade all three together when camoufox ships stable
-cross-platform binaries. Rationale in full:
-`src/infrastructure/browser/thread-worker-browser.ts`.
+`camoufox-js` to its `0.10.x` line; the three are coupled and upgraded together, because
+each floating range broke fresh consumer installs that our lockfile masked.
+playwright-core stays at `1.60.0` (1.61+ rejects camoufox's Juggler and fails every
+launch — corroborated upstream, since camoufox-js `0.12.0` declares
+`peerDependencies: { "playwright-core": "<1.61.0" }`, the same bound this pin holds by
+hand). `impit` stays at `0.13.0`: camoufox-js 0.10.2 requires `^0.13.0`, and within that
+range only 0.13.0 lacks the `only-allow pnpm` preinstall guard that breaks
+`npm install -g` (an upstream mistake in 0.13.1/0.14.0, dropped again in 0.14.1). An
+exact pin is required because npm `overrides` do not propagate to consumers. Rationale in
+full: `src/infrastructure/browser/thread-worker-browser.ts`.
+
+The two original blockers have both lapsed — camoufox restored Windows binaries in
+`v152.0.4-beta.26` (2026-07-16) and impit's guard is long gone — but camoufox-js `0.12.0`
+is held back by a third, worse one: it requires `better-sqlite3 ^13.0.1`, and
+better-sqlite3 13 **dropped prebuilt binaries**. 12.x installs via
+`prebuild-install || node-gyp rebuild`; 13.x ships no install script at all, so npm
+auto-runs `node-gyp rebuild` against its `binding.gyp` and every install demands a full
+C++ toolchain. This was measured, not inferred: the upgrade was made, and `npm ci` failed
+outright on the Windows CI runner (`could not find a version of Visual Studio 2017 or
+newer`) — i.e. it would break installation for most Windows users, which is exactly what
+this pin exists to prevent. Check better-sqlite3 before camoufox next time.
+
+The browser BINARY, by contrast, is not pinned and cannot be. `camoufox-js fetch` takes
+no version argument: it walks the `daijro/camoufox` GitHub releases newest-first and takes
+the first non-prerelease release carrying an asset for this OS/arch. So the binary a
+consumer gets is whatever camoufox published most recently at install time, regardless of
+which camoufox-js version is installed — the npm pins do not freeze it, and a future
+camoufox release could break launches for fresh installs with no change on our side.
+Windows assets were in fact missing from `v146-hardware` through `v152.0.2-alpha` and
+returned in `v152.0.4-beta.26` (2026-07-16). Current newest is `v152.0.4-beta.28`
+(Firefox 152); it launches and drives cleanly under playwright-core `1.60.0` **with
+camoufox-js 0.10.2** (whose `MIN_VERSION` is `beta.19`, so it accepts it), verified
+directly, as does the older `v135.0.1-beta.24` an existing cache may still hold. The
+practical consequence is that browser freshness is independent of the npm pin: a stale
+`camoufox-js` does not mean a stale Firefox. Re-verify a real launch when bumping this
+stack — the unit and integration suites mock the browser and cannot catch a Juggler
+mismatch.
 
 Pinned data stack — `apache-arrow` is a direct dependency at `21.1.0`, and `overrides`
 forces the whole tree to that single version so LanceDB and Arrow share one Arrow instance
 (mismatched Arrow copies do not interoperate — arrays built by one are rejected by the
-other). This sits above `@lancedb/lancedb` 0.29's declared Arrow peer ceiling
-(`>=15.0.0 <=18.1.0`); it is verified working, but the override should be re-validated
-whenever `@lancedb/lancedb` is upgraded.
+other). This sits above `@lancedb/lancedb` 0.37's declared Arrow peer ceiling
+(`>=15.0.0 <=18.1.0`) — npm will not even resolve the pairing without the override — and
+it is verified working, but it should be re-validated whenever `@lancedb/lancedb` is
+upgraded.
+
+`21.1.0` is exact for a measured reason, not caution. Bumping the PATCH-looking minor to
+`21.2.0` breaks the store outright: LanceDB's Rust-side Arrow reader cannot parse the
+schema that Arrow 21.2 writes, failing every table open with
+`Failed to read IPC file: Arrow error: Parser error: Unable to get root as footer:
+RangeOutOfBounds … UnionVariant { variant: "Type::FixedSizeList" }` — 56 unit and 36
+integration tests, every one that touches a real table. Do not treat this range as
+caret-safe. Note also that every `@lancedb/lancedb` release through 0.37 declares the same
+`<=18.1.0` Arrow ceiling, so upgrading LanceDB does not resolve the override; it only
+changes which pairing needs re-validating.
 
 Pinned validation library — `typebox` is pinned to the exact version the pi host packages
 depend on (`@earendil-works/pi-ai` / `@earendil-works/pi-coding-agent` 0.84.2 pin `1.3.7`). Every

package/docs/CHANGELOG.md

@@ -5,6 +5,72 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [1.3.12] - 2026-08-15
+
+A six-way independent audit of the whole tree (core/orchestration/LLM,
+infrastructure/security, knowledge + scrape pipeline, tools/TUI/CLI,
+release/CI/docs, and test-suite integrity), run against the clean 1.3.11 tree,
+followed by a second pass that exercised each external integration live rather
+than reading it. Every new regression test is mutation-verified — re-run against
+the reinstated pre-fix code and confirmed to fail.
+
+### Fixed
+
+- **`security_search` returned the oldest CVEs on record and could not reach recent ones.** NVD 2.0 returns keyword matches oldest-first and offers no sort parameter (`sortBy` is a 404), so paging from index 0 and stopping at `maxResults` deterministically kept the least useful window. Measured against the live API: a search for `openssl` returned CVE-1999-0428 through 2004 out of 566 matches, and nothing published after 2004 was reachable at any page size — the researcher was being handed 27-year-old advisories as the current vulnerability picture. The client now reads `totalResults` from the first page and seeks once to the tail, then orders the window newest-first (undated entries last). Only fires when the match set is larger than what is returned, so a query whose results already fit still costs exactly one request. The same search now returns the 20 most recent, through 2026-08-13. OSV had a milder form of this — its per-package list is in ID order, so truncation dropped advisories on alphabetical accident — and is now sorted newest-first before the cut.
+- **The NVD rate limiter could leave a search permanently unsettled.** The inter-request spacing timer (up to 6s without an API key) was `unref`'d, but that timer *is* the operation — nothing else settles the awaited promise. With no other ref'd handle, Node treated the process as idle mid-search and the promise never resolved: no result, no error, no timeout. Reproduced deterministically as soon as a second request was issued. It is now ref'd, and remains bounded and abortable so shutdown cannot be delayed beyond one spacing interval. Every other `unref` in the tree guards a timeout against real I/O that holds the loop open by itself; this was the only one with nothing behind it.
+- **ReDoS in the JWT redaction pattern, the sibling the 1.3.9 fix did not reach.** Bounding the URL-credential scheme fixed one quadratic pattern and left an identical one next to it: JWT segments exclude `.`, so an unbounded `[A-Za-z0-9_-]+` consumes to the end of a dotless base64url run and then backtracks one character at a time — and because `_` counts as a non-alphanumeric left boundary, the same run offers a fresh start position every few characters. Measured 393ms of blocked event loop per log message across the 40 000-character scan window, on a function that runs for every log line over largely untrusted content. Bounding the segments brings the identical input to 41ms with no loss of coverage; the bounds sit far above any real token.
+- **`PI_RESEARCH_DISABLED_TOOLS` and the SDK's `excludeTools` accepted unknown tool names silently.** `RESEARCH_TOOL_NAMES` documents itself as the vocabulary all three exclusion surfaces accept, but only `--exclude-tools` validated against it — the other two reached the same blind Set union, where a typo excludes nothing while the user believes the tool is off for a whole billed run. Both now warn at the shared chokepoint, naming the offending value and the valid set. A warning rather than an error there: that path serves a library API and an ambient env var, where aborting a legitimate request over one unrecognized name is the wrong trade. The CLI keeps its fail-fast.
+
+- **`PI_RESEARCH_STATE_DIR` pointed one directory short could wipe `config.env` and the knowledge store.** `scripts/cleanup.cjs` decided whether an override was safe to remove wholesale by testing whether `<dirName>/research` appeared as any two adjacent path segments — a naming-convention match, not the ownership proof its own comment required. That also matched the research **root** (`~/.pi/research`, which holds `config.env` and `knowledge_db/`), unrelated directories beneath it (`/mnt/backup/.pi/research/mystate`), and traversal forms (`.../research/state/../../..`) that resolve outside our tree entirely — each taking a recursive `rmSync` with no prompt. Dropping the documented `/state` suffix is a one-directory-off mistake the runtime honors literally, so a deliberate `npm run cleanup` could silently destroy every saved setting and the entire knowledge store. The check now requires the full default shape — the resolved path's trailing segments being `<dirName>/research/state` — which keeps a relocated-but-default layout reclaimable while refusing the root, siblings, and traversal escapes; everything else falls through to the targeted, filename-scoped sweep.
+- **The GPU lock could be stolen from a live process that was still using it.** The staleness backstop was a hardcoded 5 minutes, which exactly equalled the default `EMBEDDING_MODEL_INIT_TIMEOUT_MS` (300000, schema max 600000) — and the embedder holds that lock across the whole model download plus pipeline load. Dead owners are already reclaimed separately via PID+startTime liveness, so this path only ever fires against a process just proven alive: a first-time model fetch running inside its own permitted budget would have the lock taken out from under it, re-admitting exactly the concurrent WebGPU/Dawn initialization the lock exists to prevent. The threshold is now 15 minutes, strictly above the configurable maximum hold.
+- **The CPU-fallback embedder load leaked a native ONNX session on timeout.** `loadPipelineWithTimeout` grew a late-arrival disposal guard in 1.3.11, but the sibling `loadModelOnCPU` — the path taken *after* a WebGPU failure, on a host already under memory pressure — kept the same uncancellable `withTimeout` race with no such guard, orphaning one native session per retry. It now disposes the late arrival identically.
+- **Concurrent knowledge searches tore down each other's TUI indicator.** The widget ID is a single global slot and the tool is `executionMode: 'parallel'` (and separately drivable via `/knowledge-store`), so the first search to finish removed the panel while a sibling was still running. Show/hide is now reference-counted; only the last one out removes it.
+- **`registerAndReplace()` had no disposal-in-flight guard.** Unlike `clear()`/`replace()`/`disposeAll()`, it read and disposed `registration.instance` without joining an in-flight `disposalPromise`, then swapped the whole registration object — so a concurrent teardown could dispose the same instance twice and have its replacement orphaned. Currently unreachable (no call sites), fixed as a latent landmine.
+- **The SSRF-safe undici `Agent` was never released, and was not actually a singleton.** It is meant to be one process-lifetime instance holding keep-alive sockets to every host scraped; the CLI hard-exits so it never noticed, but an embedding host (the pi extension) survives SDK init/shutdown cycles. Two problems: nothing ever closed it, and the cache held the *resolved value*, assigned only after `await import('undici')` — so every concurrent first caller passed the `undefined` check, built its own `Agent`, and all but the last were handed live instances the cache never referenced. Those opened sockets that no shutdown path could ever close, which is the very leak being fixed; scrapes run concurrently by design, so the first burst hit it. The cache now holds the construction *promise*, so concurrent callers join one build, and `shutdownResearchSDK()` closes it and clears the cache — awaiting an in-flight construction rather than orphaning it — so a later re-initialization rebuilds instead of reusing a closed Agent.
+- **A cancelled run reported itself as a component failure in `--json`.** A Ctrl-C unwinding through the planner surfaces internally as `Coordinator failed: Request was aborted`, and that raw wording was emitted as the payload's `error`. The plain-text branch has always refused to say "failed" for a deliberate stop — "Cancellation is a completed intention, not a failure" — but JSON said it anyway, and SKILL.md instructs agents to relay these messages, so a user who pressed Ctrl-C was told the coordinator broke. `error` now reads `pi-research research cancelled.` with the original wording preserved under `cause`; `cancelled`, `exitCode` and the absence of `retryable` are unchanged. Verified against a real interrupted run: exit 130, correct payload.
+- **Two prompts hardcoded the stale-year examples that `injectCurrentDate` was deliberately generalized away from.** That helper derives its examples from the current year precisely so the guidance "stays correct in any year (a hardcoded '2024 or 2025' reads wrong from 2027 on)" — and the coordinator and evaluator templates then said exactly `2024 or 2025` in their own bodies, duplicating the injected guidance with values that expire. From January 2027 they would have told the model the stale years were 2024/2025 while the actually-stale ones were 2025/2026, implicitly legitimising the year to avoid. Both now refer to the injected anchor instead of restating years.
+- **`PLAYWRIGHT_BROWSERS_PATH` moved where the browser was looked for but never where it was installed** — plumbing added, and the documentation corrected to stop overclaiming. It was documented as overriding "where the camoufox binary is stored and looked up" and only ever did the second half: camoufox-js below 0.12.0 hardcodes `userCacheDir("camoufox")` and honours no variable at all. Setting it downloads to the default cache, leaves the postinstall's "already installed" probe permanently unsatisfied (so every install re-fetches), and makes the runtime report the browser missing right after a successful download. `CAMOUFOX_INSTALL_DIR` — the variable camoufox-js 0.12.0 introduced — now takes precedence, `PLAYWRIGHT_BROWSERS_PATH` is an alias, and both the postinstall fetch and the browser workers are handed it. **This is inert on the pinned camoufox-js 0.10.x** (see the dependency note below for why the pin cannot advance), so the plumbing is correct-and-waiting rather than a live fix; `CONFIGURATION.md` now states plainly that a custom browser directory is unsupported until the pin moves.
+
+### Tests
+
+- The 1.3.11 backup-pruner TTL retention fix — a silent permanent-data-loss fix — shipped with no regression test. Six now cover it (retention inside the TTL, pruning past it, never deleting the newest, ranking by the trailing backup timestamp rather than whole-name sort, migration-temp reaping, and never touching a temp-named live table); two fail against the pre-fix code.
+- `task-execution-service`'s module-level liveness-probe cache (1s) and restart cooldown (10s) both outlive a test, and the reset seam that existed for exactly this had zero callers — leaving the suite order-dependent. The seam now resets both globals and is called in `beforeEach`.
+- `cli-bridge-env.test.ts` wrote fixtures into the real home directory; a hard kill before its cleanup stranded them with nothing to sweep up. It now redirects `HOME`/`USERPROFILE` to a temp dir.
+- Fake timers in `circuit-breaker.test.ts` and `retry-utils.test.ts` were never uninstalled (`restoreAllMocks` does not do it), leaving the clock faked at file end.
+- **`verify-package` now checks that `dist/prompts` is byte-identical to `src/prompts`, not merely present.** The existing check counted files, so a stale copy passed every gate — and `dist/prompts` is what the bundled CLI and the agent-skill engine actually load. Editing a prompt without rebuilding leaves the shipped product running the old instructions with a fully green suite; that state existed in this working tree and the new check caught it. A truncated or partial copy fails here too.
+- **The shipped prompt templates are now rendered through the real substitution path and asserted to leave no `{{placeholder}}` behind**, for the coordinator and for the evaluator at all three complexity levels (its template branches on complexity, so one level passing proves little). Previously one placeholder was covered, by name, against a stub template — so adding a placeholder to a `.md` without wiring it into the call map sent literal braces to the model as instructions it could not act on. The test reads the real files, so it cannot drift from what ships.
+- New coverage for the NVD recency seek (tail offset requested, no extra request when results already fit, newest-first ordering) and for the rate-limiter timer staying ref'd — the last asserted directly, because that failure is invisible under a test runner, which always holds the event loop open by itself.
+- **The JWT ReDoS regression test asserts a complexity class rather than a wall-clock budget.** Its first form used a 200ms threshold with roughly 2× headroom, which cannot work here: the 193-file parallel suite inflated a 41ms post-fix pass to 288ms, overlapping the ~393ms pre-fix cost on an idle machine, so any fixed number either flakes under load or stops catching the regression. It now doubles the input and requires the cost not to more than double — both measurements inflate together under load, so the ratio is stable. Measured 1.87× fixed against 4.01× unbounded on the raw pattern (2.06× through `redactSecrets`), threshold 3.0, mutation-verified at 4.80× against the pre-fix pattern.
+
+### Changed
+
+- **npm keywords aligned with the repository's GitHub topics.** All eight topics (`agent-skills`, `ai-research`, `browser-automation`, `claude-code`, `llm-tools`, `web-access`, `web-scraping`, `web-search`) are now present; `claude-code` and `codex` were missing entirely despite both being first-class agent-skill install targets alongside the already-listed `openclaw`. Added rather than replaced: `pi-package` is load-bearing, not decorative — pi's own package documentation states the pi.dev gallery lists packages carrying that keyword, so swapping the list wholesale for the GitHub topics would have delisted this package from the pi ecosystem. pi has no separate tag field of its own (its manifest accepts only `extensions`/`skills`/`prompts`/`themes`/`video`/`image`), so npm `keywords` is the single tag surface for both registries.
+
+### Added
+
+- **`status` now reports whether the stealth browser is installed**, with the exact command to fix it. This became urgent rather than cosmetic: npm 11.19 blocks package install scripts by default, so a fresh `npm install -g @lincoln504/pi-research` now skips this package's `postinstall` — and therefore the camoufox download — while reporting success. Verified by installing the packed tarball under npm 11.19: everything else survives (onnxruntime, sharp, esbuild and webgpu all ship prebuilt platform packages, and `dist/` is in the tarball), so the browser is the single casualty and nothing else signals it. Previously `status` answered `ready: true` with no browser present and the first symptom was a scrape degrading mid-run. A missing browser is reported alongside `ready` rather than folded into it, because the fetch path still serves most pages. The check is a resolve plus an `existsSync` — it never launches anything.
+
+### Dependencies
+
+Every upgrade below was validated by actually running the subsystem it touches, not by a green suite alone — the browser is mocked throughout the test suite, so a Juggler mismatch would reach production with the whole unit suite passing.
+
+- **Browser binary refreshed to Firefox 152 without moving the npm pin.** The camoufox *binary* is fetched dynamically and is not governed by the `camoufox-js` version, so `v152.0.4-beta.28` (Firefox 152) runs fine on the pinned camoufox-js 0.10.2, whose `MIN_VERSION` of `beta.19` accepts it. That closes a real staleness gap — the stealth browser had been presenting Firefox 135 from March 2025 while the fetch path advertised Firefox 153, itself a bot signal. Verified by launching and driving a real browser (both 152.0.4-beta.28 and the older 135.0.1-beta.24 launch, navigate and report a correct UA under playwright-core 1.60.0) and by all 13 live-network search/scrape connectivity tests.
+- **`camoufox-js` stays on ^0.10.2 and `impit` on 0.13.0 — attempted, measured, reverted.** Both blockers ARCHITECTURE.md recorded had genuinely lapsed (camoufox restored Windows assets in `v152.0.4-beta.26`; impit's `only-allow pnpm` guard existed only in 0.13.1/0.14.0), so the upgrade was made — and CI caught a third, worse blocker on Windows. camoufox-js 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`, while 13.x ships no install script at all, so npm auto-runs `node-gyp rebuild` against its `binding.gyp` and every install demands a full C++ toolchain. `npm ci` failed outright on the Windows runner (`could not find a version of Visual Studio 2017 or newer`) — i.e. it would break installation for most Windows users, exactly what this pin exists to prevent. The blocker is now better understood than before: check better-sqlite3 first, not camoufox.
+- **`@lancedb/lancedb` 0.29.0 → 0.37.1.** Validated beyond the suite: 0.37.1 opens a real 116 MB, 2249-row store written by 0.29 and serves a live knowledge search against it with real embeddings. Two measured invariants the store's own code depends on were re-checked and hold: the three commit-conflict strings `isLanceCommitConflict` matches are still present in the 0.37.1 native binary, and `createIndex` still advances `version()` by exactly one for a vector index, an FTS index and a `replace: true` rebuild alike.
+- **`youtubei.js` ^17 → ^18** (live transcript fetch verified) and **`@types/jsdom` ^28 → ^30**.
+
+Held deliberately, each for a checked reason rather than caution:
+
+- **`apache-arrow` stays at `21.1.0`.** The minor bump to 21.2.0 breaks the knowledge store outright — LanceDB's Rust-side reader cannot parse the schema Arrow 21.2 writes, failing every real-table open with `Unable to get root as footer: RangeOutOfBounds … Type::FixedSizeList`, across 56 unit and 36 integration tests. Attempted, measured, reverted; the pin's rationale is now empirical rather than assumed.
+- **`bgutils-js` stays at ^3.** v4 removes the root export entirely (no `"."` in its `exports` map), so the `await import('bgutils-js')` the PoToken path uses would throw outright, and restructures the API (`Challenge.create` → a free `getChallenge`, `BotGuardClient` now event-emitter based with a different `snapshot` shape). That is a rewrite of the most fragile integration in the tree, and v3 demonstrably works — a live transcript fetch succeeds today.
+- **`playwright-core` stays at `1.60.0`** (camoufox-js peer range, above) and **`typebox` at `1.3.7`** (pi 0.84.2, the newest published, pins exactly that).
+- **`typescript` stays in `>=6.0.3 <6.1.0`.** TypeScript 7 is unusable here regardless of its own merits: typescript-eslint's newest release (8.67.0) still declares `typescript: ">=4.8.4 <6.1.0"` and hardcodes the same supported range, so 7.x would break linting. 6.0.3 is already the newest release in the supported line.
+
+### Verified, no change needed
+
+- Every external integration was exercised against its live API rather than read: NVD, OSV, CISA KEV, and GitHub Advisories all return current data; YouTube transcripts resolve correctly despite `youtubei.js` and `bgutils-js` each being a major behind; StackExchange returns canonical high-score answers on the path the tool actually uses. CISA KEV and GitHub Advisories already order results deliberately (by due date and `direction=desc` respectively) and were left alone.
+- The published package points `pi.extensions` at raw `src/`, which contains two `enum`s and parameter properties — both fatal under Node's strip-only type stripping. pi loads extensions through `jiti`, which transpiles fully, so this is safe; noted because the failure mode would be a total load failure, not a degradation.
+
 ## [1.3.11] - 2026-08-14
 
 Alongside the revert below, a four-way independent audit (docs-vs-code

package/docs/CONFIGURATION.md

@@ -79,7 +79,7 @@ Research
 | `PI_RESEARCH_MAX_CONCURRENT_RUNS` | `3` | ≥1 | Machine-wide cap on research runs executing at the same time, across **every** process (CLI, agent skill, pi extension, SDK). Runs beyond the cap queue rather than fail. All concurrent runs share one leader-elected browser/embedding pool, so oversubscribing it degrades every run at once. |
 | `PI_RESEARCH_RUN_ACQUIRE_TIMEOUT_MS` | `600000` | ≥0 | How long a run queues for a free slot before failing with "maximum concurrent research runs reached" (CLI exit `75`). `0` = fail immediately instead of queueing. |
 | `PI_RESEARCH_MODEL` | _(pi: session model; CLI/skill: required)_ | — | The model research runs on. **Required for the standalone CLI / agent skill** — they use only this configured model (never the model selected inside the pi extension) and refuse to start without one (the CLI's per-run `--model` flag also satisfies this). On the SDK it selects the session model when no `model` option is given. In the pi extension it overrides researcher sub-agents and knowledge synthesis, while the coordinator and evaluator keep using the session model. Accepts `provider/id` or a bare model id. |
-| `PI_RESEARCH_DISABLED_TOOLS` | _(none)_ | — | Comma-separated research tools to disable for a run (`search`, `scrape`, `security_search`, `stackexchange`, `youtube_transcript`, `grep`). Removed from every researcher's toolset and named in the coordinator/evaluator prompt. Strictly additive — it can only remove capabilities, never grant one, and it stacks on top of the default exclusions rather than replacing them. |
+| `PI_RESEARCH_DISABLED_TOOLS` | _(none)_ | — | Comma-separated research tools to disable for a run (`search`, `scrape`, `security_search`, `stackexchange`, `youtube_transcript`, `grep`, `read`). Removed from every researcher's toolset and named in the coordinator/evaluator prompt. Strictly additive — it can only remove capabilities, never grant one, and it stacks on top of the default exclusions rather than replacing them. An unrecognized name excludes nothing and is warned about rather than failing the run. |
 | `PI_RESEARCH_REPORT_EXPORT_ENABLED` (TUI) | `false` | — | Front-ends write a Markdown report to disk and surface its path. |
 | `PI_RESEARCH_REPORT_EXPORT_DIR` | _(smart cwd)_ | — | Pin exported reports to a fixed directory, bypassing the cwd-relative resolution. Useful for the agent skill, which runs from the host agent's arbitrary directory. |
 | `PI_RESEARCH_MAX_SCRAPE_TOKEN_FRACTION_FOR_SCRAPING` | `0.15` | 0.05–1.0 | Max fraction of the context window used for initial scrape context. |
@@ -156,7 +156,8 @@ Diagnostics & platform
 | `PI_RESEARCH_SKILL_DIR` | _(auto)_ | Override the bundled research-skill source directory used by the skill installer. |
 | `PI_RESEARCH_PURGE_BROWSERS` | _(unset)_ | Read by the bundled `scripts/cleanup.cjs`: set `1` to also delete the shared camoufox browser cache (kept by default because other installs may use it). Note npm ≥7 does not run `preuninstall`, so that script does not fire on `npm uninstall` — see [AGENT-SKILL.md](AGENT-SKILL.md). |
 | `PLAYWRIGHT_SKIP_BROWSER_DOWNLOAD` | _(unset)_ | Set `1` during `npm install` to skip the camoufox browser download (fetched lazily on first use instead; standard Playwright convention). |
-| `PLAYWRIGHT_BROWSERS_PATH` | _(user cache)_ | Standard Playwright variable, honoured here too: overrides where the camoufox binary is stored and looked up, and is passed through to browser workers. |
+| `CAMOUFOX_INSTALL_DIR` | _(user cache)_ | camoufox-js's own variable, and the only one that can relocate the browser. Sets where pi-research looks the binary up, and is exported to the postinstall fetch and to browser workers. **Not effective on the currently pinned camoufox-js (0.10.x), which hardcodes its cache directory and honours no variable** — so relocating the browser is unsupported until that pin can advance (see ARCHITECTURE.md). |
+| `PLAYWRIGHT_BROWSERS_PATH` | _(user cache)_ | Alias for the above, accepted for compatibility and exported onward as `CAMOUFOX_INSTALL_DIR`. Same caveat: on the pinned camoufox-js it moves only where pi-research looks, not where the download lands, so setting it reports the browser missing from the custom path after a successful install. |
 | `XDG_CACHE_HOME` | `~/.cache` | Standard XDG variable. When set, every `~/.cache/pi-research/...` path below is rooted at `$XDG_CACHE_HOME/pi-research/...` instead. |
 | `PI_RESEARCH_BIN` (alias `PI_RESEARCH_PATH`) | _(auto)_ | Agent-skill launcher only: explicit path to the pi-research engine binary when auto-resolution (PATH → local install → npx) should be bypassed. See [skills/pi-research/references/configuration.md](../skills/pi-research/references/configuration.md). |
 | `PLAYWRIGHT_INSTALL_DEPS` | _(unset)_ | Linux only. Set `true` during `npm install` to also install system libraries via `npx playwright install-deps` (same as `npm run install:system-deps`). |