@lincoln504/pi-research 1.0.5 → 1.0.8

package/docs/CONFIGURATION.md

@@ -73,6 +73,7 @@ Research
 | `PI_RESEARCH_MAX_CONCURRENT_SCRAPES` | `3` | 1–20 | Concurrent URLs fetched per scrape batch. |
 | `PI_RESEARCH_MAX_RETRIES` | `2` | 0–5 | Retries per researcher request. |
 | `PI_RESEARCH_RETRY_DELAY_MS` | `2000` | 100–10000 | Base delay between retries. |
+| `PI_RESEARCH_MAX_FAILED_RESEARCHERS` | `2` | 1–10 | Unique researcher failures that abort the whole run. Raise to let slower, still-in-flight researchers finish before giving up. |
 | `PI_RESEARCH_WORKER_THREADS` | `4` | 1–10 | Browser worker processes. Higher = more throughput, more CPU/RAM. |
 | `PI_RESEARCH_WORKER_CONCURRENCY` | `2` | 1–10 | Tasks per worker process. |
 | `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. |

package/docs/SDK.md

@@ -76,7 +76,10 @@ await shutdownResearchSDK();
 `runResearchDetailed`, `searchKnowledge`, `scrapeUrl`, `getResearchHealth`,
 `getLastRunStats`, and `getSessionMetrics`, plus `exportKnowledge` (write the
 knowledge store to a web-consumable JSON file) and the post-run telemetry accessors
-`getLastRunMetrics`, `getLastRunSummary`, and `getLastErrorReport`. Both
+`getLastRunMetrics`, `getLastRunSummary`, `getLastErrorReport`, and
+`getLastResearcherOutcome` (planned/launched/succeeded/failed researcher counts plus
+per-researcher failure reasons for the most recent run — lets a caller tell a thin
+report caused by a sparse topic apart from one where most researchers failed). Both
 `@lincoln504/pi-research` and `@lincoln504/pi-research/sdk` export these symbols.
 
 > Concurrency: a single initialized SDK instance runs one research call at a time.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@lincoln504/pi-research",
-  "version": "1.0.5",
+  "version": "1.0.8",
   "description": "A set of web research tools (search, scrape, and others) and research agent system that uses them safely and efficiently.",
   "type": "module",
   "private": false,
@@ -37,7 +37,8 @@
     "scripts/prepare.cjs",
     "LICENSE",
     "docs/THIRD-PARTY-NOTICES.md",
-    "README.md"
+    "README.md",
+    "docs/CHANGELOG.md"
   ],
   "repository": {
     "type": "git",
@@ -109,9 +110,9 @@
     "image": "https://raw.githubusercontent.com/Lincoln504/pi-research/main/docs/media/hero.png"
   },
   "dependencies": {
-    "@earendil-works/pi-ai": ">=0.80.2 <1",
-    "@earendil-works/pi-coding-agent": ">=0.80.2 <1",
-    "@earendil-works/pi-tui": ">=0.80.2 <1",
+    "@earendil-works/pi-ai": ">=0.80.7 <1",
+    "@earendil-works/pi-coding-agent": ">=0.80.7 <1",
+    "@earendil-works/pi-tui": ">=0.80.7 <1",
     "@huggingface/transformers": "4.2.0",
     "@kreuzberg/html-to-markdown-node": "^3.5.5",
     "@lancedb/lancedb": "0.29.0",

package/skills/pi-research/SKILL.md

@@ -2,7 +2,7 @@
 name: pi-research
 description: "Multi-agent web research for any coding agent. Use for anything requiring current information from the internet — news, trends, product/service/company facts, statistics, people, places, events, APIs, library behavior, or 'what is X / how does X work' questions. Also use to search a local knowledge store of previously researched findings before doing live research. Powered by the pi-research engine (search, stealth scraping, security databases, Stack Exchange). Not for reading local files, running project commands, or analyzing this repository's own source."
 license: MIT
-metadata: { "author": "Lincoln Deen", "version": "1.0.5", "package": "@lincoln504/pi-research", "engine": "pi-research-sdk", "openclaw": { "requires": { "bins": ["node"] } } }
+metadata: { "author": "Lincoln Deen", "version": "1.0.8", "package": "@lincoln504/pi-research", "engine": "pi-research-sdk", "openclaw": { "requires": { "bins": ["node"] } } }
 allowed-tools: Bash(node:*)
 ---
 

package/src/cli.ts

@@ -31,9 +31,12 @@ import {
   runDeepResearch,
   searchKnowledge,
   shutdownResearchSDK,
+  getLastErrorReport,
+  getLastResearcherOutcome,
   type KnowledgeSearchResult,
 } from './sdk.ts';
 import type { HeadlessObserverOptions } from './orchestration/headless-observer.ts';
+import { RESEARCH_STOPPED_ERROR_CODE } from './orchestration/session-state.ts';
 import { validateAndSanitizeQuery } from './utils/input-validation.ts';
 import { validateInitialLink, MAX_INITIAL_LINKS } from './utils/url-utils.ts';
 import { exportResearchReport, appendExportMessage } from './utils/research-export.ts';
@@ -468,6 +471,11 @@ async function cmdResearch(args: ResearchArgs): Promise<number> {
   const observer: HeadlessObserverOptions = makeProgressObserver();
 
   let exit: number = EXIT.OK;
+  // Let Ctrl-C/SIGTERM (main()'s onSignal) cancel THIS run's orchestrator instead of
+  // only tearing down shared SDK services out from under it — see
+  // activeResearchAbortController's declaration for why.
+  const abortController = new AbortController();
+  activeResearchAbortController = abortController;
   try {
     await initResearchSDK({
       model: runModel,
@@ -485,7 +493,7 @@ async function cmdResearch(args: ResearchArgs): Promise<number> {
       observer,
       ...(args.excludeTools ? { excludeTools: args.excludeTools } : {}),
       ...(args.initialLinks ? { initialLinks: args.initialLinks } : {}),
-    });
+    }, abortController.signal);
 
     // Optionally persist the report to a file (opt-in via
     // PI_RESEARCH_REPORT_EXPORT_ENABLED). The SDK is a pure library and does not
@@ -503,13 +511,29 @@ async function cmdResearch(args: ResearchArgs): Promise<number> {
     }
 
     if (args.json) {
-      toStdout(pretty({ ok: true, depth, report, ...(reportPath ? { reportPath } : {}) }));
+      // Surface the internal quality/health signals that were previously log-only
+      // (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();
+      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;
@@ -791,12 +815,23 @@ function describeUninstall(r: { status: string; path: string; message?: string }
 // ---------------------------------------------------------------------------
 
 /** Distinguish setup errors from runtime errors and print a clean, located message. */
-function reportError(err: unknown, what: string, json?: boolean): number {
+export function reportError(err: unknown, what: string, json?: boolean): number {
   const msg = err instanceof Error ? err.message : String(err);
   const lower = msg.toLowerCase();
 
+  // A tagged research-stop error (session-state.ts's createResearchStopError) is an
+  // orchestration/infrastructure failure (worker-pool contention, ungrounded
+  // researchers, etc.), never a credentials problem — classify it as SOFTWARE
+  // unconditionally and skip the substring heuristic below entirely. Without this,
+  // the boilerplate advice line every research-stop message carries ("Verify the
+  // model is available and the API key / context settings are valid.") contains the
+  // literal substring "api key," so the heuristic alone would misclassify EVERY
+  // research-stop — regardless of real cause — as a config error (exit 78).
+  const isTaggedResearchStop = (err as { code?: unknown } | undefined)?.code === RESEARCH_STOPPED_ERROR_CODE;
+
   // Auth / model / config-shaped errors → CONFIG exit + config block.
   const isConfigError =
+    !isTaggedResearchStop && (
     lower.includes('no llm model available') ||
     lower.includes('not found in pi') ||
     lower.includes('no api key') ||
@@ -804,7 +839,7 @@ function reportError(err: unknown, what: string, json?: boolean): number {
     lower.includes('invalid model string') ||
     lower.includes('authentication') ||
     lower.includes('unauthorized') ||
-    lower.includes('api key');
+    lower.includes('api key'));
 
   // Rate limits win over config-shaped matches: a provider 429 often mentions
   // "api key" in its body (e.g. "rate limit exceeded for this api key"), and
@@ -1175,6 +1210,15 @@ const flushAndExit = (code: number): void => {
   });
 };
 
+// Signal to the in-flight `research` run's AbortController, if any is active.
+// Without this, Ctrl-C only tore down shared SDK services (browser pool, LLM
+// clients, LanceDB) via safeShutdown() while runDeepResearch() was still using
+// them — the orchestrator never saw a cancellation and had no chance to return
+// its already-wired partial/fallback synthesis for a clean stop. Set at the
+// start of cmdResearch, cleared in its finally so a stale reference never
+// outlives that one run.
+let activeResearchAbortController: AbortController | null = null;
+
 async function main(argv: string[]): Promise<number> {
   // Register signal handlers so SIGINT/SIGTERM always trigger SDK shutdown
   // before the process exits. safeShutdown() is idempotent — safe to call
@@ -1184,6 +1228,11 @@ async function main(argv: string[]): Promise<number> {
     if (_signalCleanupDone) return;
     _signalCleanupDone = true;
     toStderr(`\n[pi-research] ${sig} — cleaning up…\n`);
+    // Abort the in-flight research run FIRST (synchronously ahead of the shutdown
+    // teardown below) so the orchestrator's existing signal-aware cancellation path
+    // gets a chance to return a partial/fallback synthesis instead of racing a live
+    // browser-pool/LLM teardown out from under it.
+    activeResearchAbortController?.abort();
     // Fire-and-forget: we can't await here, but safeShutdown swallows errors
     // and the finally blocks in each command handler also call it. Drain via
     // flushAndExit (not a bare process.exit) so buffered stdout isn't truncated.

package/src/config.ts

@@ -28,6 +28,8 @@ export const 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: 10000, default: 2000 }),
+  /** 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) */
@@ -690,6 +692,7 @@ export function saveConfig(config: Config, scope: 'local' | 'user' = 'local', cw
     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),
@@ -912,6 +915,7 @@ export function createConfig(env: Record<string, string | undefined>, 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, 10000),
+    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),

package/src/index.ts

@@ -53,6 +53,8 @@ export {
   getLastRunSummary,
   getLastErrorReport,
   getLastRunStats,
+  getLastResearcherOutcome,
+  type ResearcherOutcome,
   getSessionMetrics,
   getResearchHealth,
   runQuickResearch,

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

@@ -99,11 +99,17 @@ export async function runBrowserTask<T>(
                 await waitForBrowserPoolIdle(15000).catch((err) => logger.debug('Wait for browser idle timed out or failed:', err));
             } else {
                 // True socket/connection error — restart the scheduler with thundering herd guard.
+                // Do NOT force-clear remote leader state here: a transient socket
+                // hiccup against a live-but-busy leader is not proof the leader is
+                // dead. forceSchedulerRestart(false) still clears state when its own
+                // PID+start-time liveness probe confirms the registered leader is
+                // actually gone; it only skips clearing when that probe finds the
+                // leader alive, which is exactly the case we must not disturb.
                 const now = Date.now();
                 if (now - lastRestartTime > RESTART_COOLDOWN_MS) {
                     lastRestartTime = now;
                     logger.warn(`[BrowserManager] Forcing scheduler restart and retrying...`);
-                    await forceSchedulerRestart(true, container);
+                    await forceSchedulerRestart(false, container);
                     await waitForBrowserPoolIdle(15000).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...`);
@@ -141,11 +147,14 @@ export async function runBrowserHealthCheck(config?: Config, retries = 1, signal
             if (isPoolShutdownError(error)) {
                 await waitForBrowserPoolIdle(15000).catch((err) => logger.debug('Wait for browser idle timed out or failed:', err));
             } else {
+                // See runBrowserTask: don't force-clear remote leader state on a bare
+                // transient socket error — let the liveness probe inside
+                // forceSchedulerRestart decide.
                 const now = Date.now();
                 if (now - lastRestartTime > RESTART_COOLDOWN_MS) {
                     lastRestartTime = now;
                     logger.warn(`[BrowserManager] Forcing scheduler restart and retrying...`);
-                    await forceSchedulerRestart(true, container);
+                    await forceSchedulerRestart(false, container);
                     await waitForBrowserPoolIdle(15000).catch((err) => logger.debug('Wait for browser idle timed out or failed:', err));
                 } else {
                     await waitForBrowserPoolIdle(15000).catch((err) => logger.debug('Wait for browser idle timed out or failed:', err));
@@ -189,11 +198,14 @@ export async function runWorkerSearch(query: string, config?: Config, signal?: A
             if (isPoolShutdownError(error)) {
                 await waitForBrowserPoolIdle(15000).catch((err) => logger.debug('Wait for browser idle timed out or failed:', err));
             } else {
+                // See runBrowserTask: don't force-clear remote leader state on a bare
+                // transient socket error — let the liveness probe inside
+                // forceSchedulerRestart decide.
                 const now = Date.now();
                 if (now - lastRestartTime > RESTART_COOLDOWN_MS) {
                     lastRestartTime = now;
                     logger.warn(`[BrowserManager] Forcing scheduler restart and retrying...`);
-                    await forceSchedulerRestart(true, container);
+                    await forceSchedulerRestart(false, container);
                     await waitForBrowserPoolIdle(15000).catch((err) => logger.debug('Wait for browser idle timed out or failed:', err));
                 } else {
                     await waitForBrowserPoolIdle(15000).catch((err) => logger.debug('Wait for browser idle timed out or failed:', err));

package/src/infrastructure/browser/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/src/orchestration/headless-observer.ts

@@ -24,16 +24,23 @@ export type { HeadlessObserverOptions };
  * rejections never become unhandled.
  */
 export function makeSafeObserver<T extends object>(observer: T): T {
-  return new Proxy(observer, {
-    get(target, prop) {
-      // Guard the ACCESS too, and resolve getters against the target (not the
-      // proxy): an observer exposing a method via an accessor that touches a
-      // private field would otherwise throw at `observer?.onX?.(...)` property
-      // access — outside the call-site try/catch below — which is exactly the
-      // failure this wrapper exists to absorb.
+  // Proxy a FRESH empty object and close over the real observer instead of
+  // proxying the observer directly: a `get` trap on the observer itself may
+  // not substitute a wrapper for a non-writable non-configurable own data
+  // property (Proxy invariant), so a frozen observer — a common defensive
+  // pattern for SDK callback bags — would make the engine throw TypeError at
+  // the property ACCESS, outside every try/catch. An empty target has no own
+  // properties, so no invariant can ever bind the trap.
+  return new Proxy({} as T, {
+    get(_target, prop) {
+      // Guard the ACCESS too, and resolve getters against the observer (not
+      // the proxy): an observer exposing a method via an accessor that touches
+      // a private field would otherwise throw at `observer?.onX?.(...)`
+      // property access — outside the call-site try/catch below — which is
+      // exactly the failure this wrapper exists to absorb.
       let value: unknown;
       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 undefined;
@@ -41,7 +48,7 @@ export function makeSafeObserver<T extends object>(observer: T): T {
       if (typeof value !== 'function') return value;
       return (...args: unknown[]) => {
         try {
-          const out = value.apply(target, args);
+          const out = value.apply(observer, args);
           if (out && typeof (out as Promise<unknown>).then === 'function') {
             return (out as Promise<unknown>).catch((err: unknown) => {
               logger.warn(`[observer] Ignored rejection from observer.${String(prop)}:`, err);
@@ -54,6 +61,17 @@ export function makeSafeObserver<T extends object>(observer: T): T {
         }
       };
     },
+    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);
+    },
   }) as T;
 }
 

package/src/orchestration/research-orchestration-service.ts

@@ -37,7 +37,7 @@ import type { Config } from '../config.ts';
 import { getConfig, DEFAULTS } from '../config.ts';
 import { getCachedScrapedContent, normalizeUrl, cleanupSharedLinks } from '../utils/shared-links.ts';
 import { runResearcher } from './researcher-executor.ts';
-import { recordResearcherFailure, shouldStopResearch, getResearchStopMessage } from './session-state.ts';
+import { recordResearcherFailure, shouldStopResearch, createResearchStopError } from './session-state.ts';
 import type { ResearchSessionService } from './research-session-service.ts';
 import { QuickResearchOrchestrator } from './quick-research-orchestrator.ts';
 import { DeepResearchOrchestrator } from './deep-research-orchestrator.ts';
@@ -291,6 +291,7 @@ export class ResearchOrchestrationService implements IResearchOrchestration {
     const active = new Set<Promise<void>>();
     // Honour MAX_CONCURRENT_RESEARCHERS — prevents resource spikes when a plan has many researchers.
     const maxConcurrent: number = (orchestratorOptions.config as Config)?.MAX_CONCURRENT_RESEARCHERS ?? DEFAULTS.MAX_CONCURRENT_RESEARCHERS;
+    const maxFailedResearchers: number = (orchestratorOptions.config as Config)?.MAX_FAILED_RESEARCHERS ?? DEFAULTS.MAX_FAILED_RESEARCHERS;
 
     for (const configItem of researchers) {
       if (signal?.aborted) break;
@@ -299,10 +300,10 @@ export class ResearchOrchestrationService implements IResearchOrchestration {
       // post-launch check below only fires after a researcher is in-flight, so
       // without this an early check, up to maxConcurrent-1 extra researchers could
       // start past the stop threshold and waste a browser slot + an LLM call.
-      if (shouldStopResearch(sessionId, researchId)) {
+      if (shouldStopResearch(sessionId, researchId, maxFailedResearchers)) {
         const sessionService = await getService<ResearchSessionService>(ServiceNames.RESEARCH_SESSION_SERVICE, ctx, container);
         await sessionService.abortAllSessions(researchId);
-        throw new Error(getResearchStopMessage(sessionId, researchId));
+        throw createResearchStopError(sessionId, researchId);
       }
 
       // Enforce the concurrency cap before launching the next researcher.
@@ -391,13 +392,12 @@ export class ResearchOrchestrationService implements IResearchOrchestration {
         if (signal?.aborted) break;
       }
 
-      if (shouldStopResearch(sessionId, researchId)) {
+      if (shouldStopResearch(sessionId, researchId, maxFailedResearchers)) {
         const sessionService = await getService<ResearchSessionService>(ServiceNames.RESEARCH_SESSION_SERVICE, ctx, container);
         // Abort sessions specifically for this researchId, not the whole piSessionId
         await sessionService.abortAllSessions(researchId);
 
-        const stopMessage = getResearchStopMessage(sessionId, researchId);
-        throw new Error(stopMessage);
+        throw createResearchStopError(sessionId, researchId);
       }
     }
 

package/src/orchestration/research-synthesis-service.ts

@@ -178,28 +178,39 @@ export class ResearchSynthesisService implements IService {
     let globalCitations: GlobalCitation[] =
       reports.size > 0 ? normalizeCitations(reports).globalCitations : [];
 
-    // Robustness fallback: if the reports yielded no parseable citations — e.g. the
-    // LLM omitted or mangled its "CITED LINKS" block, or wrote the sources under a
-    // heading parseCitations does not recognize — rebuild the sources list from the
-    // ground-truth provenance: the URLs the researchers ACTUALLY, successfully
-    // scraped this session (registerScrapedLinks only records HTTP-success fetches).
-    // This decouples the final sources list from fragile LLM prose formatting so that
-    // real fetched sources are never silently lost.
-    if (globalCitations.length === 0) {
+    // Robustness fallback: reconcile against ground-truth provenance — the URLs
+    // ACTUALLY, successfully scraped this session (registerScrapedLinks only records
+    // HTTP-success fetches). This runs even when SOME citations parsed: a
+    // multi-researcher run where only one researcher's report has an unparseable/
+    // missing "CITED LINKS" block still needs that researcher's real sources folded
+    // in — gating this on globalCitations being entirely EMPTY only ever caught the
+    // all-researchers-failed-to-cite case and silently dropped a partial researcher's
+    // sources whenever ANY other researcher cited normally. Only URLs not already
+    // represented (by normalized URL) are added, so parsed citations — richer, with
+    // descriptions and source tags — are never overwritten.
+    if (reports.size > 0) {
       const scraped = getScrapedLinks(sessionId);
       if (scraped.length > 0) {
-        // Label per actual provenance: the pool also contains transcript watch
-        // URLs the youtube_transcript tool registered — calling those "Scrape"
-        // misattributes the report's real source material.
-        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;
+          // Label per actual provenance: the pool also contains transcript watch
+          // URLs the youtube_transcript tool registered — calling those "Scrape"
+          // misattributes the report's real source material.
+          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.`,
+          );
+        }
       }
     }
 

package/src/orchestration/researcher-executor.ts

@@ -21,6 +21,7 @@ import { loadPrompt } from '../core/llm/prompts.ts';
 import { injectCurrentDate } from '../core/llm/inject-date.ts';
 import { recordResearcherFailure, getSteeringMessages } from './session-state.ts';
 import type { RunResearcherOptions } from './orchestration-types.ts';
+import { search } from '../web-research/search.ts';
 
 /**
  * Run a single researcher with retries
@@ -62,22 +63,59 @@ export async function runResearcher(options: RunResearcherOptions): Promise<void
   }
 
   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.`);
-    // Use the resolved sessionId (= piSessionId), NOT the raw ctx.sessionId: when
-    // ctx.sessionId is unset but sessionManager supplies a real id (common in SDK
-    // use), recording under ctx.sessionId would file this no-links skip under a
-    // different id than shouldStopResearch() checks, so the fast-stop guard would
-    // under-count exactly the broad-search-failure case it exists to catch.
-    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) {
+    // The plan-wide initial search burst (run once, before any researcher starts)
+    // can come back empty for THIS researcher's queries specifically because the
+    // shared browser pool was mid-recovery (e.g. leader-election churn, see
+    // task-execution-service.ts) at that exact moment — not because the topic has
+    // no results. Unlike every other researcher failure mode, this one used to
+    // `return` immediately, bypassing RESEARCHER_MAX_RETRIES entirely: a single
+    // transient pool hiccup counted as a full, unretried researcher failure and,
+    // combined with MAX_FAILED_RESEARCHERS, could abort a run with several other
+    // researchers still healthy and in flight. Give it the same bounded retry
+    // budget as the rest of this function, re-issuing a fresh search for this
+    // researcher's own queries before giving up.
+    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 delay = Math.min(1000 * 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 ${delay}ms`);
+        await new Promise(r => setTimeout(r, delay));
+      }
+      if (signal?.aborted || container?.isDisposing) break;
+      try {
+        const queryResults = await search(retryQueries, config, signal, undefined, container);
+        const urls = new Set<string>();
+        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.`);
+      // Use the resolved sessionId (= piSessionId), NOT the raw ctx.sessionId: when
+      // ctx.sessionId is unset but sessionManager supplies a real id (common in SDK
+      // use), recording under ctx.sessionId would file this no-links skip under a
+      // different id than shouldStopResearch() checks, so the fast-stop guard would
+      // under-count exactly the broad-search-failure case it exists to catch.
+      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) {
-    evidenceSection = `## Evidence Provided\nInitial search results provided the following URLs to investigate:\n${initialLinks.map(l => `- ${l}`).join('\n')}`;
+  if (effectiveInitialLinks.length > 0) {
+    evidenceSection = `## Evidence Provided\nInitial search results provided the following URLs to investigate:\n${effectiveInitialLinks.map(l => `- ${l}`).join('\n')}`;
   }
 
   const maxAttempts = config.RESEARCHER_MAX_RETRIES + 1;

package/src/orchestration/session-state.ts

@@ -605,16 +605,18 @@ export function getFailedResearchers(piSessionId: string | undefined, researchId
 }
 
 /**
- * Maximum allowed unique failed researchers
+ * Default (and fallback, for callers not passing a resolved Config) max allowed
+ * unique failed researchers before the run aborts. Configurable per-run via
+ * Config.MAX_FAILED_RESEARCHERS / PI_RESEARCH_MAX_FAILED_RESEARCHERS.
  */
-const MAX_FAILED_RESEARCHERS = 2;
+const DEFAULT_MAX_FAILED_RESEARCHERS = 2;
 
 /**
  * Check if research should stop due to too many unique failures
  */
-export function shouldStopResearch(piSessionId: string | undefined, researchId: string): boolean {
+export function shouldStopResearch(piSessionId: string | undefined, researchId: string, maxFailedResearchers: number = DEFAULT_MAX_FAILED_RESEARCHERS): boolean {
   const sid = normalizeSessionId(piSessionId);
-  return getFailedResearchers(sid, researchId).length >= MAX_FAILED_RESEARCHERS;
+  return getFailedResearchers(sid, researchId).length >= maxFailedResearchers;
 }
 
 /**
@@ -659,6 +661,27 @@ export function getResearchStopMessage(piSessionId: string | undefined, research
   ].join('\n');
 }
 
+/**
+ * Stable error code for a fail-fast research-stop error. cli.ts's reportError()
+ * checks this BEFORE its 'api key'-substring config-error heuristic: the
+ * boilerplate advice line above ("...API key / context settings are valid.")
+ * is appended to every research-stop message regardless of cause, so a
+ * substring match alone misclassifies every worker-pool/infra-driven stop as
+ * a config error (exit 78) instead of a software error (exit 70).
+ */
+export const RESEARCH_STOPPED_ERROR_CODE = 'RESEARCH_STOPPED';
+
+/**
+ * Build the Error to throw when shouldStopResearch() trips, tagged with
+ * RESEARCH_STOPPED_ERROR_CODE so callers can classify it without re-parsing
+ * the (human-oriented, boilerplate-laden) message text.
+ */
+export function createResearchStopError(piSessionId: string | undefined, researchId: string): Error & { code: string } {
+  const err = new Error(getResearchStopMessage(piSessionId, researchId)) as Error & { code: string };
+  err.code = RESEARCH_STOPPED_ERROR_CODE;
+  return err;
+}
+
 /**
  * Get all active research panels in a Pi session, in display order (newest first)
  */

package/src/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.