@lincoln504/pi-research 1.0.5 → 1.0.8

package/dist/cli.mjs

@@ -2295,6 +2295,7 @@ function saveConfig(config, scope = "local", cwd = process.cwd(), changedKeys) {
     PI_RESEARCH_MAX_RESEARCHERS: String(config.MAX_CONCURRENT_RESEARCHERS),
     PI_RESEARCH_MAX_RETRIES: String(config.RESEARCHER_MAX_RETRIES),
     PI_RESEARCH_RETRY_DELAY_MS: String(config.RESEARCHER_MAX_RETRY_DELAY_MS),
+    PI_RESEARCH_MAX_FAILED_RESEARCHERS: String(config.MAX_FAILED_RESEARCHERS ?? DEFAULTS.MAX_FAILED_RESEARCHERS),
     PI_RESEARCH_HEALTH_CHECK_TIMEOUT_MS: String(config.HEALTH_CHECK_TIMEOUT_MS ?? DEFAULTS.HEALTH_CHECK_TIMEOUT_MS),
     PI_RESEARCH_SEARCH_TIMEOUT_MS: String(config.SEARCH_TIMEOUT_MS),
     PI_RESEARCH_TUI_REFRESH_DEBOUNCE_MS: String(config.TUI_REFRESH_DEBOUNCE_MS),
@@ -2457,6 +2458,7 @@ function createConfig(env, processEnv) {
     MAX_CONCURRENT_RESEARCHERS: parseEnvNumber(e, "PI_RESEARCH_MAX_RESEARCHERS", DEFAULTS.MAX_CONCURRENT_RESEARCHERS, 1, 5, true),
     RESEARCHER_MAX_RETRIES: parseEnvNumber(e, "PI_RESEARCH_MAX_RETRIES", DEFAULTS.RESEARCHER_MAX_RETRIES, 0, 5, true),
     RESEARCHER_MAX_RETRY_DELAY_MS: parseEnvNumber(e, "PI_RESEARCH_RETRY_DELAY_MS", DEFAULTS.RESEARCHER_MAX_RETRY_DELAY_MS, 100, 1e4),
+    MAX_FAILED_RESEARCHERS: parseEnvNumber(e, "PI_RESEARCH_MAX_FAILED_RESEARCHERS", DEFAULTS.MAX_FAILED_RESEARCHERS, 1, 10, true),
     DEFAULT_RESEARCH_DEPTH: parseEnvNumber(e, "PI_RESEARCH_DEFAULT_RESEARCH_DEPTH", DEFAULTS.DEFAULT_RESEARCH_DEPTH, 1, 3, true),
     MAX_SCRAPE_BATCHES: parseEnvNumber(e, "PI_RESEARCH_MAX_SCRAPE_BATCHES", DEFAULTS.MAX_SCRAPE_BATCHES, 0, 99, true),
     MAX_GATHERING_CALLS: parseEnvNumber(e, "PI_RESEARCH_MAX_GATHERING_CALLS", DEFAULTS.MAX_GATHERING_CALLS, 1, 100, true),
@@ -2580,6 +2582,8 @@ var init_config = __esm({
       RESEARCHER_MAX_RETRIES: Type.Number({ minimum: 0, maximum: 5, default: 2 }),
       /** Base delay between retries in milliseconds (default: 2000, range: 100-10000) */
       RESEARCHER_MAX_RETRY_DELAY_MS: Type.Number({ minimum: 100, maximum: 1e4, default: 2e3 }),
+      /** Unique researcher failures that abort the entire run (default: 2, range: 1-10) */
+      MAX_FAILED_RESEARCHERS: Type.Number({ minimum: 1, maximum: 10, default: 2 }),
       /** Target depth for recursive research (default: 1, range: 1-3) */
       DEFAULT_RESEARCH_DEPTH: Type.Number({ minimum: 1, maximum: 3, default: 1 }),
       /** Number of batches to allow for a single scrape tool call (default: 2, 0=unlimited) */
@@ -14650,7 +14654,7 @@ async function runBrowserTask(taskOrUrl, type = "scrape", config, signal, retrie
         if (now - lastRestartTime > RESTART_COOLDOWN_MS) {
           lastRestartTime = now;
           logger.warn(`[BrowserManager] Forcing scheduler restart and retrying...`);
-          await forceSchedulerRestart2(true, container);
+          await forceSchedulerRestart2(false, container);
           await waitForBrowserPoolIdle(15e3).catch((err) => logger.debug("Wait for browser idle timed out or failed:", err));
         } else {
           logger.warn(`[BrowserManager] Scheduler restart recently triggered, waiting for pool idle...`);
@@ -14685,7 +14689,7 @@ async function runBrowserHealthCheck(config, retries = 1, signal, container = ge
         if (now - lastRestartTime > RESTART_COOLDOWN_MS) {
           lastRestartTime = now;
           logger.warn(`[BrowserManager] Forcing scheduler restart and retrying...`);
-          await forceSchedulerRestart2(true, container);
+          await forceSchedulerRestart2(false, container);
           await waitForBrowserPoolIdle(15e3).catch((err) => logger.debug("Wait for browser idle timed out or failed:", err));
         } else {
           await waitForBrowserPoolIdle(15e3).catch((err) => logger.debug("Wait for browser idle timed out or failed:", err));
@@ -14724,7 +14728,7 @@ async function runWorkerSearch(query, config, signal, retries = 1, sessionId, co
         if (now - lastRestartTime > RESTART_COOLDOWN_MS) {
           lastRestartTime = now;
           logger.warn(`[BrowserManager] Forcing scheduler restart and retrying...`);
-          await forceSchedulerRestart2(true, container);
+          await forceSchedulerRestart2(false, container);
           await waitForBrowserPoolIdle(15e3).catch((err) => logger.debug("Wait for browser idle timed out or failed:", err));
         } else {
           await waitForBrowserPoolIdle(15e3).catch((err) => logger.debug("Wait for browser idle timed out or failed:", err));
@@ -19445,10 +19449,8 @@ function formatResults(results, rejected) {
     if (typeof r.charCount === "number") meta.push(`${r.charCount.toLocaleString()} chars`);
     if (meta.length) md += `**${meta.join(" \xB7 ")}**
 `;
-    if (r.title) {
-      md += `**Cite as:** ${r.url} \u2014 '${r.title}'${r.author ? ` by ${r.author}` : ""}
+    md += `**Cite as:** ${r.url}${r.title ? ` \u2014 '${r.title}'${r.author ? ` by ${r.author}` : ""}` : ""}
 `;
-    }
     md += `
 ${r.text}
 
@@ -20108,10 +20110,10 @@ function getFailedResearchers(piSessionId, researchId) {
   const failures = state.failures.get(researchId) || [];
   return [...new Set(failures)];
 }
-var MAX_FAILED_RESEARCHERS = 2;
-function shouldStopResearch(piSessionId, researchId) {
+var DEFAULT_MAX_FAILED_RESEARCHERS = 2;
+function shouldStopResearch(piSessionId, researchId, maxFailedResearchers = DEFAULT_MAX_FAILED_RESEARCHERS) {
   const sid = normalizeSessionId(piSessionId);
-  return getFailedResearchers(sid, researchId).length >= MAX_FAILED_RESEARCHERS;
+  return getFailedResearchers(sid, researchId).length >= maxFailedResearchers;
 }
 function getResearchStopMessage(piSessionId, researchId) {
   const sid = normalizeSessionId(piSessionId);
@@ -20137,6 +20139,12 @@ function getResearchStopMessage(piSessionId, researchId) {
     "Partial results may be available below."
   ].join("\n");
 }
+var RESEARCH_STOPPED_ERROR_CODE = "RESEARCH_STOPPED";
+function createResearchStopError(piSessionId, researchId) {
+  const err = new Error(getResearchStopMessage(piSessionId, researchId));
+  err.code = RESEARCH_STOPPED_ERROR_CODE;
+  return err;
+}
 
 // src/orchestration/researcher-executor.ts
 async function runResearcher(options) {
@@ -20171,18 +20179,42 @@ ${currentPlan.allQueries.map((q) => `- ${q}`).join("\n")}
   Previous summary: ${e.description}`).join("\n");
   }
   const researcherPromptTemplate = loadPrompt("researcher");
-  if (initialLinks.length === 0 && historicalUrls.length === 0) {
-    logger.warn(`[ResearcherExecutor] Researcher ${id} has no initial search results or historical links; skipping.`);
-    recordResearcherFailure(sessionId, researchId, id, "no initial search results or historical links (search produced nothing usable)");
-    metrics.increment("researcher_skipped_total", 1, { mode: "deep", complexity: String(complexity), reason: "no_initial_links" });
-    observer?.onResearcherFailure?.(id, "No initial search results or historical links available");
-    return;
+  let effectiveInitialLinks = initialLinks;
+  if (effectiveInitialLinks.length === 0 && historicalUrls.length === 0) {
+    const retryQueries = researcherConfig.queries?.length ? researcherConfig.queries : [researcherConfig.goal];
+    const maxLinkAttempts = config.RESEARCHER_MAX_RETRIES + 1;
+    for (let linkAttempt = 1; linkAttempt <= maxLinkAttempts && effectiveInitialLinks.length === 0; linkAttempt++) {
+      if (linkAttempt > 1) {
+        if (signal?.aborted || container?.isDisposing) break;
+        const delay2 = Math.min(1e3 * Math.pow(2, linkAttempt - 2), config.RESEARCHER_MAX_RETRY_DELAY_MS);
+        logger.warn(`[ResearcherExecutor] Researcher ${id} has no initial search results; retry ${linkAttempt - 1}/${config.RESEARCHER_MAX_RETRIES} after ${delay2}ms`);
+        await new Promise((r) => setTimeout(r, delay2));
+      }
+      if (signal?.aborted || container?.isDisposing) break;
+      try {
+        const queryResults = await search(retryQueries, config, signal, void 0, container);
+        const urls = /* @__PURE__ */ new Set();
+        for (const qr of queryResults) {
+          for (const r of qr.results || []) urls.add(r.url);
+        }
+        effectiveInitialLinks = [...urls];
+      } catch (err) {
+        logger.debug(`[ResearcherExecutor] Researcher ${id} link-retry search burst failed:`, err);
+      }
+    }
+    if (effectiveInitialLinks.length === 0) {
+      logger.warn(`[ResearcherExecutor] Researcher ${id} has no initial search results or historical links after ${maxLinkAttempts} attempt(s); skipping.`);
+      recordResearcherFailure(sessionId, researchId, id, "no initial search results or historical links (search produced nothing usable)");
+      metrics.increment("researcher_skipped_total", 1, { mode: "deep", complexity: String(complexity), reason: "no_initial_links" });
+      observer?.onResearcherFailure?.(id, "No initial search results or historical links available");
+      return;
+    }
   }
   let evidenceSection = "";
-  if (initialLinks.length > 0) {
+  if (effectiveInitialLinks.length > 0) {
     evidenceSection = `## Evidence Provided
 Initial search results provided the following URLs to investigate:
-${initialLinks.map((l) => `- ${l}`).join("\n")}`;
+${effectiveInitialLinks.map((l) => `- ${l}`).join("\n")}`;
   }
   const maxAttempts = config.RESEARCHER_MAX_RETRIES + 1;
   let lastError;
@@ -20428,11 +20460,11 @@ init_constants();
 // src/orchestration/headless-observer.ts
 init_logger();
 function makeSafeObserver(observer) {
-  return new Proxy(observer, {
-    get(target, prop) {
+  return new Proxy({}, {
+    get(_target, prop) {
       let value;
       try {
-        value = Reflect.get(target, prop, target);
+        value = Reflect.get(observer, prop, observer);
       } catch (err) {
         logger.warn(`[observer] Ignored error reading observer.${String(prop)}:`, err);
         return void 0;
@@ -20440,7 +20472,7 @@ function makeSafeObserver(observer) {
       if (typeof value !== "function") return value;
       return (...args) => {
         try {
-          const out = value.apply(target, args);
+          const out = value.apply(observer, args);
           if (out && typeof out.then === "function") {
             return out.catch((err) => {
               logger.warn(`[observer] Ignored rejection from observer.${String(prop)}:`, err);
@@ -20452,6 +20484,17 @@ function makeSafeObserver(observer) {
           return void 0;
         }
       };
+    },
+    has(_target, prop) {
+      try {
+        return Reflect.has(observer, prop);
+      } catch {
+        return false;
+      }
+    },
+    // Keep `instanceof` transparent (legal on an extensible target).
+    getPrototypeOf() {
+      return Reflect.getPrototypeOf(observer);
     }
   });
 }
@@ -21403,12 +21446,13 @@ var ResearchOrchestrationService = class {
     const researchers = plan.researchers || [];
     const active = /* @__PURE__ */ new Set();
     const maxConcurrent = orchestratorOptions.config?.MAX_CONCURRENT_RESEARCHERS ?? DEFAULTS.MAX_CONCURRENT_RESEARCHERS;
+    const maxFailedResearchers = orchestratorOptions.config?.MAX_FAILED_RESEARCHERS ?? DEFAULTS.MAX_FAILED_RESEARCHERS;
     for (const configItem of researchers) {
       if (signal?.aborted) break;
-      if (shouldStopResearch(sessionId, researchId)) {
+      if (shouldStopResearch(sessionId, researchId, maxFailedResearchers)) {
         const sessionService = await getService(ServiceNames.RESEARCH_SESSION_SERVICE, ctx, container);
         await sessionService.abortAllSessions(researchId);
-        throw new Error(getResearchStopMessage(sessionId, researchId));
+        throw createResearchStopError(sessionId, researchId);
       }
       if (active.size >= maxConcurrent) {
         if (signal?.aborted) break;
@@ -21477,11 +21521,10 @@ var ResearchOrchestrationService = class {
         });
         if (signal?.aborted) break;
       }
-      if (shouldStopResearch(sessionId, researchId)) {
+      if (shouldStopResearch(sessionId, researchId, maxFailedResearchers)) {
         const sessionService = await getService(ServiceNames.RESEARCH_SESSION_SERVICE, ctx, container);
         await sessionService.abortAllSessions(researchId);
-        const stopMessage = getResearchStopMessage(sessionId, researchId);
-        throw new Error(stopMessage);
+        throw createResearchStopError(sessionId, researchId);
       }
     }
     await Promise.all(active);
@@ -21878,18 +21921,26 @@ Research performed using ${modelId}`;
   ensureCitedLinks(sessionId, synthesis) {
     const reports = this.getSessionReports(sessionId);
     let globalCitations = reports.size > 0 ? normalizeCitations(reports).globalCitations : [];
-    if (globalCitations.length === 0) {
+    if (reports.size > 0) {
       const scraped = getScrapedLinks(sessionId);
       if (scraped.length > 0) {
-        globalCitations = scraped.map((url, i) => ({
-          id: i + 1,
-          url,
-          description: "",
-          source: isTranscribedLink(sessionId, url) ? "YouTube Transcript" : "Scrape"
-        }));
-        logger.warn(
-          `[ResearchSynthesisService] No citations parsed from reports; rebuilt ${scraped.length} source(s) from scrape/transcript provenance.`
-        );
+        const known = new Set(globalCitations.map((c) => normalizeUrl(c.url)));
+        const missing = scraped.filter((url) => !known.has(normalizeUrl(url)));
+        if (missing.length > 0) {
+          const startId = globalCitations.reduce((max, c) => Math.max(max, c.id), 0) + 1;
+          globalCitations = [
+            ...globalCitations,
+            ...missing.map((url, i) => ({
+              id: startId + i,
+              url,
+              description: "",
+              source: isTranscribedLink(sessionId, url) ? "YouTube Transcript" : "Scrape"
+            }))
+          ];
+          logger.warn(
+            `[ResearchSynthesisService] Folded in ${missing.length} source(s) from scrape/transcript provenance not covered by parsed citations.`
+          );
+        }
       }
     }
     if (globalCitations.length > 0) {
@@ -22103,6 +22154,79 @@ init_metrics();
 
 // src/utils/metrics-summary.ts
 init_text_utils();
+function sumCounter(counters, baseName) {
+  let total = 0;
+  for (const [key, value] of Object.entries(counters)) {
+    if (key === baseName || key.startsWith(baseName + "{")) {
+      total += value;
+    }
+  }
+  return total;
+}
+function getLabeledCounter(counters, baseName, labels) {
+  const labelParts = Object.entries(labels).map(([k, v]) => `${k}="${v}"`);
+  const suffix = `{${labelParts.join(",")}}`;
+  for (const [key, value] of Object.entries(counters)) {
+    if (key === `${baseName}${suffix}`) {
+      return value;
+    }
+  }
+  return 0;
+}
+function extractRunStats(snapshot) {
+  const counters = snapshot.counters || {};
+  const histograms = snapshot.histograms || {};
+  const researchersLaunched = sumCounter(counters, "researchers_launched_total");
+  const browserSearchQueries = sumCounter(counters, "browser_search_queries_total");
+  const searchQueries = sumCounter(counters, "search_queries_total") + browserSearchQueries;
+  const urlsDiscovered = sumCounter(counters, "browser_search_results_total") + sumCounter(counters, "browser_search_unique_urls_total");
+  const fetchSuccess = getLabeledCounter(counters, "scrape_results_total", { outcome: "fetch_success" });
+  const browserSuccess = getLabeledCounter(counters, "scrape_results_total", { outcome: "browser_success" });
+  const totalFailure = getLabeledCounter(counters, "scrape_results_total", { outcome: "total_failure" });
+  const browserFallbacks = sumCounter(counters, "scrape_layer_fallbacks_total");
+  const urlsAnalyzed = fetchSuccess + browserSuccess;
+  const urlsFailed = totalFailure;
+  const toolUsage = {
+    searches: sumCounter(counters, "tool_search_calls_total"),
+    scrapes: sumCounter(counters, "tool_scrape_calls_total"),
+    securitySearches: sumCounter(counters, "tool_security_search_calls_total"),
+    stackexchangeQueries: sumCounter(counters, "stackexchange_requests_total"),
+    knowledgeLookups: sumCounter(counters, "research_knowledge_search_total")
+  };
+  const errors = sumCounter(counters, "researcher_errors_total") + sumCounter(counters, "llm_api_errors_total");
+  const tokens = sumCounter(counters, "llm_tokens_total");
+  const cost = sumCounter(counters, "llm_cost_total");
+  const durationMs = histograms['research_session_duration_ms{mode="deep",complexity="1",status="success"}']?.max || histograms['research_session_duration_ms{mode="deep",complexity="2",status="success"}']?.max || histograms['research_session_duration_ms{mode="deep",complexity="3",status="success"}']?.max || histograms['research_session_duration_ms{mode="quick",complexity="0",status="success"}']?.max || 0;
+  const roundsCompleted = sumCounter(counters, "evaluator_runs_total");
+  let complexity = 1;
+  for (const key of Object.keys(counters)) {
+    if (key.startsWith("research_sessions_total{")) {
+      const match = key.match(/complexity="(\d+)"/);
+      if (match?.[1]) complexity = parseInt(match[1], 10);
+      break;
+    }
+  }
+  if (researchersLaunched === 0 && searchQueries === 0 && urlsAnalyzed === 0 && tokens === 0) {
+    return null;
+  }
+  return {
+    durationMs,
+    complexity,
+    researchersLaunched,
+    roundsCompleted,
+    searchQueries,
+    urlsDiscovered,
+    fetchSuccess,
+    browserSuccess,
+    browserFallbacks,
+    urlsAnalyzed,
+    urlsFailed,
+    errors,
+    tokens,
+    cost,
+    toolUsage
+  };
+}
 
 // src/sdk.ts
 init_error_tracker();
@@ -22124,6 +22248,7 @@ var _isRunning = false;
 var _lastResearchId = null;
 var _lastRunSummary = null;
 var _lastErrorReport = null;
+var _lastResearcherOutcome = null;
 var _onSignal = null;
 var _sigintHandler = null;
 var _sigtermHandler = null;
@@ -22310,6 +22435,7 @@ async function runDeepResearch(query, options = {}, signal) {
     metrics.recordRunSummary(_lastRunSummary);
     _lastErrorReport = runTracker.getReport();
     logRunErrorSummary(_lastErrorReport, depthLabel, "success");
+    _lastResearcherOutcome = await captureResearcherOutcome(sessionId, researchId, _lastRunSummary.snapshot);
     return result;
   } catch (err) {
     const completedAt = Date.now();
@@ -22325,6 +22451,7 @@ async function runDeepResearch(query, options = {}, signal) {
     metrics.recordRunSummary(_lastRunSummary);
     _lastErrorReport = runTracker.getReport();
     logRunErrorSummary(_lastErrorReport, depthLabel, "error");
+    _lastResearcherOutcome = await captureResearcherOutcome(sessionId, researchId, _lastRunSummary.snapshot);
     throw err;
   } finally {
     try {
@@ -22334,11 +22461,35 @@ async function runDeepResearch(query, options = {}, signal) {
     _isRunning = false;
   }
 }
+function getLastErrorReport() {
+  return _lastErrorReport;
+}
+function getLastResearcherOutcome() {
+  return _lastResearcherOutcome;
+}
 function logRunErrorSummary(report, depthLabel, status) {
   if (!report || report.totalErrors === 0) return;
   const top = report.patterns.slice(0, 3).map((p) => `"${String(p.message ?? p.signature ?? "error").slice(0, 48)}" \xD7${p.count}`).join(", ");
   logger.warn(`[SDK] run ${status} with ${report.totalErrors} tracked error(s) across ${report.uniquePatterns} pattern(s) [${depthLabel}]${top ? ` \u2014 top: ${top}` : ""}`);
 }
+async function captureResearcherOutcome(sessionId, researchId, snapshot) {
+  try {
+    const planningService = await getService(ServiceNames.PLANNING, void 0, globalContainer);
+    const planned = planningService.getTotalResearchersPlanned(researchId);
+    const launched = extractRunStats(snapshot)?.researchersLaunched ?? 0;
+    const failed = getFailedResearchers(sessionId, researchId);
+    return {
+      planned,
+      launched,
+      succeeded: Math.max(0, launched - failed.length),
+      failed: failed.length,
+      failureReasons: getResearcherFailureReasons(sessionId, researchId)
+    };
+  } catch (err) {
+    logger.debug("[SDK] Failed to capture researcher outcome (non-fatal):", err);
+    return null;
+  }
+}
 async function searchKnowledge(queries, signal) {
   if (!isInitialized || !globalContainer) {
     throw new Error("SDK not initialized. Call initResearchSDK() first.");
@@ -22422,6 +22573,7 @@ async function _doShutdown() {
   _lastResearchId = null;
   _lastRunSummary = null;
   _lastErrorReport = null;
+  _lastResearcherOutcome = null;
   resetConfig();
   _removeSignalHandlers();
   if (errors.length > 0) {
@@ -22927,6 +23079,8 @@ Error: ${vmsg}
 `);
   const observer = makeProgressObserver();
   let exit = EXIT.OK;
+  const abortController = new AbortController();
+  activeResearchAbortController = abortController;
   try {
     await initResearchSDK({
       model: runModel,
@@ -22943,7 +23097,7 @@ Error: ${vmsg}
       observer,
       ...args.excludeTools ? { excludeTools: args.excludeTools } : {},
       ...args.initialLinks ? { initialLinks: args.initialLinks } : {}
-    });
+    }, abortController.signal);
     let reportPath = null;
     const exportCfg = getConfig(process.cwd(), "cli");
     if (exportCfg.RESEARCH_REPORT_EXPORT_ENABLED) {
@@ -22955,13 +23109,25 @@ Error: ${vmsg}
       }
     }
     if (args.json) {
-      toStdout(pretty({ ok: true, depth, report, ...reportPath ? { reportPath } : {} }));
+      const outcome = getLastResearcherOutcome();
+      const errorReport = getLastErrorReport();
+      toStdout(pretty({
+        ok: true,
+        depth,
+        report,
+        ...reportPath ? { reportPath } : {},
+        ...outcome ? { researchers: { planned: outcome.planned, launched: outcome.launched, succeeded: outcome.succeeded, failed: outcome.failed } } : {},
+        ...errorReport && errorReport.totalErrors > 0 ? {
+          trackedErrors: { total: errorReport.totalErrors, uniquePatterns: errorReport.uniquePatterns }
+        } : {}
+      }));
     } else {
       toStdout(report.endsWith("\n") ? report : report + "\n");
     }
   } catch (err) {
     exit = reportError(err, "research", args.json);
   } finally {
+    if (activeResearchAbortController === abortController) activeResearchAbortController = null;
     await safeShutdown();
   }
   return exit;
@@ -23238,7 +23404,8 @@ function describeUninstall(r) {
 function reportError(err, what, json) {
   const msg2 = err instanceof Error ? err.message : String(err);
   const lower = msg2.toLowerCase();
-  const isConfigError = lower.includes("no llm model available") || lower.includes("not found in pi") || lower.includes("no api key") || lower.includes("provider must be specified") || lower.includes("invalid model string") || lower.includes("authentication") || lower.includes("unauthorized") || lower.includes("api key");
+  const isTaggedResearchStop = err?.code === RESEARCH_STOPPED_ERROR_CODE;
+  const isConfigError = !isTaggedResearchStop && (lower.includes("no llm model available") || lower.includes("not found in pi") || lower.includes("no api key") || lower.includes("provider must be specified") || lower.includes("invalid model string") || lower.includes("authentication") || lower.includes("unauthorized") || lower.includes("api key"));
   const isRateLimit = lower.includes("429") || lower.includes("rate limit") || lower.includes("too many requests");
   const exitCode = isConfigError && !isRateLimit ? EXIT.CONFIG : EXIT.SOFTWARE;
   if (json) {
@@ -23546,6 +23713,7 @@ var flushAndExit = (code) => {
     });
   });
 };
+var activeResearchAbortController = null;
 async function main(argv) {
   let _signalCleanupDone = false;
   const onSignal = (sig) => {
@@ -23554,6 +23722,7 @@ async function main(argv) {
     toStderr(`
 [pi-research] ${sig} \u2014 cleaning up\u2026
 `);
+    activeResearchAbortController?.abort();
     void safeShutdown().finally(() => flushAndExit(EXIT.SOFTWARE));
   };
   process.once("SIGINT", () => onSignal("SIGINT"));
@@ -23623,5 +23792,6 @@ export {
   EXIT,
   UsageError,
   bridgeConfigEnv,
-  parseArgs
+  parseArgs,
+  reportError
 };

package/dist/prompts/research-tool-usage.md

@@ -85,6 +85,7 @@ The coordinator will plan as many researchers as needed (up to the max). You do
 
 **Multiple Topics:**
 - If you need to research multiple unrelated topics of **truly distinct scope**, you may emit multiple `research` calls **simultaneously in a single turn**. Each call gets its own isolated research run with its own coordinator and researchers.
+- **Maximum 4 simultaneous calls** — Do NOT make more than 4 `research` calls in a single turn, even if you have more unrelated topics. Exceeding 4 simultaneous research runs can overload the system and degrade performance. If you have more than 4 truly distinct topics, they can likely be consolidated into fewer calls (group related subtopics, use broader queries, or batch across multiple turns).
 - Example: `research("bananas")` and `research("quantum computing")` in the same turn — these have zero overlap.
 - **Group related topics**: If topics share ANY scope or could inform each other, combine them into a single `research` call. The internal coordinator will decompose them into parallel researcher agents. Do NOT split related sub-topics into separate calls.
 - Example: `research("Python async performance and Rust async performance comparison")` — NOT separate calls for Python and Rust, since the comparison IS the research goal.

package/dist/thread-worker.mjs

@@ -2219,6 +2219,8 @@ var ConfigSchema = Type.Object({
   RESEARCHER_MAX_RETRIES: Type.Number({ minimum: 0, maximum: 5, default: 2 }),
   /** Base delay between retries in milliseconds (default: 2000, range: 100-10000) */
   RESEARCHER_MAX_RETRY_DELAY_MS: Type.Number({ minimum: 100, maximum: 1e4, default: 2e3 }),
+  /** Unique researcher failures that abort the entire run (default: 2, range: 1-10) */
+  MAX_FAILED_RESEARCHERS: Type.Number({ minimum: 1, maximum: 10, default: 2 }),
   /** Target depth for recursive research (default: 1, range: 1-3) */
   DEFAULT_RESEARCH_DEPTH: Type.Number({ minimum: 1, maximum: 3, default: 1 }),
   /** Number of batches to allow for a single scrape tool call (default: 2, 0=unlimited) */

package/docs/ARCHITECTURE.md

@@ -25,8 +25,8 @@ pi CLI
    in-session, the calling agent picks the depth (1–3) from the user's wording and the
    task's complexity, guided by the tool's usage prompt (`src/prompts/research-tool-usage.md`).
    CLI and SDK callers pass the depth explicitly.
-2. Depth 0 takes the quick path; depth 1–3 takes the deep path (below). The TUI and agent
-   skill are restricted to levels 1–3.
+2. Depth 0 takes the quick path; depth 1–3 takes the deep path (below). The pi extension's
+   tool and the TUI are restricted to levels 1–3; the CLI, SDK, and agent skill can pass 0.
 3. On the deep path the coordinator plans the research tracks and runs one initial
    search burst, then hands each researcher a set of result URLs to start from.
 4. Researchers scrape and read those pages through the scrape tooling and return cited
@@ -84,10 +84,23 @@ Two conventions apply:
   report. A mid-round evaluation that cannot be parsed continues the existing agenda
   rather than finalizing early, so a parse failure never truncates a run.
 
-### Research tools
+### Tool inventory
 
-Each researcher has a fixed tool set and a shared budget of 12 gathering calls per phase
-(`MAX_GATHERING_CALLS`).
+This is the canonical list of every tool the system exposes, on both surfaces.
+
+**Host-facing tools** — registered with the pi session (`src/index.ts`) for the calling
+agent to invoke:
+
+| Tool | Purpose |
+|------|---------|
+| `research` | Run a full multi-source research session and return the cited Markdown report |
+| `research_knowledge_search` | Instant local search of the knowledge store — checked before live research; always registered, reports why when the store is disabled |
+| `health` | Verify system status (browser pool, knowledge store, GPU lock); optional liveness probe |
+
+**Researcher-agent tools** — the fixed set each researcher sub-agent works with
+(`src/tools/index.ts`). `search`, `security_search`, `stackexchange`, and
+`youtube_transcript` share a budget of 12 gathering calls per phase
+(`MAX_GATHERING_CALLS`); `scrape` and local `grep` have their own budgets:
 
 | Tool | Quick | Deep | Backend |
 |------|-------|------|---------|
@@ -102,7 +115,9 @@ Each researcher has a fixed tool set and a shared budget of 12 gathering calls p
 In deep research `search` is excluded — the coordinator runs the search burst and hands
 out URLs directly. In quick research `grep` is excluded — the single session is not
 expected to traverse a local codebase. Researchers cannot write files, run shell
-commands, or reach the network outside these tools.
+commands, or reach the network outside these tools. Individual researcher tools can be
+disabled per run with `PI_RESEARCH_DISABLED_TOOLS`
+(see [CONFIGURATION.md](CONFIGURATION.md)).
 
 ### Browser infrastructure
 
@@ -154,7 +169,8 @@ WriterQueue (async, non-blocking)
 Key files: `src/knowledge/store.ts` (LanceDB operations), `embedder.ts` (model load +
 batched inference), `writer-queue.ts` (async writes + content-hash dedup), `chunker.ts`
 (chunking), `webgpu-viability.ts` (out-of-process GPU probe + cached verdict),
-`migration.ts` (model-change migration: drop / backup / re-embed).
+`migration.ts` (migration strategy types — the drop / backup / re-embed logic
+itself lives in `store.ts`).
 
 The store needs native ONNX-runtime and LanceDB bindings. On platforms with no prebuilt
 binary — notably Intel macOS (`darwin-x64`) — it is absent: the health check reports it

package/docs/CHANGELOG.md

@@ -0,0 +1,108 @@
+# Changelog
+
+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.0.8] - 2024-07-17
+
+### Added
+- **CHANGELOG** — Added comprehensive CHANGELOG.md documenting all versions from 0.1.13 through 1.0.7
+- **System prompt constraint** — Added "Maximum 4 simultaneous calls" constraint to research-tool-usage prompt to prevent system overload
+
+### Changed
+- **Topic consolidation guidance** — Emphasized that topics can likely be consolidated to fit the 4-call maximum, with strategies for grouping related subtopics
+- **Package structure** — CHANGELOG.md now included in published package (docs/CHANGELOG.md)
+
+## [1.0.7] - 2024-07-14
+
+### Fixed
+- **Browser-pool leader-election race** - Fixed a critical bug where a single client's transient socket error could force-clear shared leader state, causing a live, healthy leader to self-destruct via the leadership-miss watchdog. The fix reserves the "unreachable, force clear" path for cases where liveness probes actually confirm the registered leader PID or port is gone.
+- **Researcher retry-exemption** - Fixed the "no initial search results or historical links" failure path that bypassed the retry loop entirely. This now routes through the same `RESEARCHER_MAX_RETRIES`/`RESEARCHER_MAX_RETRY_DELAY_MS` retry loop as other failures.
+- **Exit-code misclassification** - Fixed false-positive classification of "Research stopped" errors as config errors (exit 78) via substring matching on the boilerplate "API key" advice text. Error classification now properly distinguishes infrastructure failures from credential problems.
+- **Unsurfaced quality signals** - Added per-run error tracking and per-researcher grounding signals to the log output for better debugging of report quality variance.
+- **SIGINT/SIGTERM cancellation wiring** - Improved cancellation handling for graceful shutdown on interrupt signals.
+- **Multi-researcher citation-provenance folding** - Fixed citation provenance tracking when multiple researchers contribute to a report.
+- **Untitled YouTube video citation line** - Fixed citation formatting for YouTube videos without titles.
+
+### Security
+- Several hardening improvements from the adversarial-review audit:
+  - Migration abort safety gates
+  - Hollow-run detection gates
+  - Streaming caps for large responses
+  - Socket drain on Content-Length pre-screen throws
+  - Observer isolation improvements
+
+## [1.0.6] - 2024-07-01
+
+### Fixed
+- **Observer isolation** - Fixed `makeSafeObserver` proxying the observer directly, which could cause state leakage.
+
+### Documentation
+- Corrected depth-0 availability documentation
+- Fixed migration.ts attribution in architecture docs
+
+## [1.0.5] - 2024-06-28
+
+### Fixed
+- **Content-Length pre-screen throws** - Added proper body draining to prevent resource leaks
+- **TTL refresh for transcribed links** - Fixed TTL handling for YouTube transcripts
+
+### Fixed
+- **YouTube transcript provenance** - Fixed transcript provenance tracking in final report citations
+
+## [1.0.4] - 2024-06-25
+
+### Fixed
+- **Credential detection** - Detect pi keys by pi's own semantics, not file presence; registry no longer gated on auth.json
+- **Configuration clarity** - Updated docs to reflect that pi has configuration files, not a named 'auth' feature
+
+## [1.0.3] - 2024-06-20
+
+### Fixed
+- **Model resolution** - Require a configured model on the standalone CLI/skill; align SDK session model with RESEARCH_MODEL
+- **Configuration requirement** - Added proper error messages when model is not configured
+
+### Documentation
+- Updated installation and configuration documentation
+
+## [1.0.2] - 2024-06-15
+
+### Fixed
+- **Timeout robustness** - Improved timeout handling for long-running operations
+- De-emphasized the markdown-conversion fallback in favor of native HTML-to-markdown conversion
+
+## [1.0.1] - 2024-06-10
+
+### Fixed
+- Initial stable release after rebuild against current pi APIs
+- Stealth-browser stack integration
+
+## [0.1.13] - 2024-04-15
+
+### Added
+- Initial research functionality
+- Knowledge store integration
+- Multi-agent orchestration
+
+---
+
+## Deferred Findings (from v1.0.7 audit)
+
+The following issues were identified during the v1.0.7 audit but intentionally deferred to future releases:
+
+1. **KnowledgeStore.close() timeout behavior** - The close() method proceeds even when the pending-write wait times out. A correct fix requires threading cancellation tokens through write paths or documenting the 10s timeout as intended behavior.
+
+2. **Cross-session teardown via shared singletons** - Session shutdown handlers run process-wide cleanup for reload/new/fork events. The correct behavior depends on pi's session model semantics and needs further investigation.
+
+3. **Lower-severity hardening items** - Various low-confidence or low-impact findings noted for future investigation:
+   - SIGINT-adjacent cancellation race
+   - Knowledge-store migration vs. concurrent access
+   - Global activity gate reused for per-session decisions
+   - Zombie queued browser tasks after timeout
+   - Non-atomic `clearBrowserServer`
+   - Inconsistent `knowledge --json` payload shapes
+   - Backward-clock-step tolerance across multiple rate limiters
+
+See `DEFERRED-FINDINGS-2026-07-14.md` for full details.