@lincoln504/pi-research 1.0.6 → 1.0.8

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.6", "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/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.

package/src/sdk.ts

@@ -22,11 +22,12 @@ import { getService, resetServiceContainer, getServiceContainer } from './core/s
 import type { ServiceContainer } from './core/service-registry.ts';
 import { ServiceNames } from './core/service-interfaces.ts';
 import type { IKnowledgeStoreService } from './core/interfaces/knowledge-interfaces.ts';
-import type { 
-  IResearchOrchestration, 
+import type {
+  IResearchOrchestration,
   IResearchSynthesisService,
-  ResearchOptions 
+  ResearchOptions
 } from './core/interfaces/orchestration-interfaces.ts';
+import type { IPlanningService } from './core/interfaces/planning-interfaces.ts';
 import type { Model } from '@earendil-works/pi-ai';
 import { type ExtensionContext, ModelRegistry } from '@earendil-works/pi-coding-agent';
 import { logger, createLogger, setLogger } from './logger.ts';
@@ -78,6 +79,22 @@ let _lastRunSummary: RunSummary | null = null;
 // run end when errors occurred, and consumers can read the full report after the run.
 let _lastErrorReport: ErrorReport | null = null;
 
+/**
+ * Researcher-outcome summary for the most recent runDeepResearch call: how many
+ * researchers were planned/launched vs. how many ultimately failed (never landed
+ * a report) vs. succeeded, plus the first recorded failure reason per failed
+ * researcher. Lets a caller distinguish "thin report, little material out there"
+ * from "thin report because most researchers died" without opening the log file.
+ */
+export interface ResearcherOutcome {
+  planned: number;
+  launched: number;
+  succeeded: number;
+  failed: number;
+  failureReasons: Record<string, string>;
+}
+let _lastResearcherOutcome: ResearcherOutcome | null = null;
+
 // Signal handler state — registered once, removed on clean shutdown.
 let _onSignal: ((signal: string) => void) | null = null;
 let _sigintHandler: (() => void) | null = null;
@@ -512,6 +529,7 @@ export async function runDeepResearch(
     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();
@@ -524,6 +542,7 @@ export async function runDeepResearch(
     metrics.recordRunSummary(_lastRunSummary);
     _lastErrorReport = runTracker.getReport();
     logRunErrorSummary(_lastErrorReport, depthLabel, 'error');
+    _lastResearcherOutcome = await captureResearcherOutcome(sessionId, researchId, _lastRunSummary.snapshot);
     throw err;
   } finally {
     // Free the per-run PiSessionState that shouldStopResearch()/getFailedResearchers()
@@ -564,6 +583,14 @@ export function getLastErrorReport(): ErrorReport | null {
   return _lastErrorReport;
 }
 
+/**
+ * Researcher-outcome summary (planned/launched/succeeded/failed + failure reasons)
+ * for the most recent run. Null until the first run completes; cleared on shutdown.
+ */
+export function getLastResearcherOutcome(): ResearcherOutcome | null {
+  return _lastResearcherOutcome;
+}
+
 /**
  * Emit a single compact line summarizing a run's tracked errors, so they are visible in
  * the operator's log instead of silently accumulating. No-op when the run was clean.
@@ -576,6 +603,31 @@ function logRunErrorSummary(report: ErrorReport | null, depthLabel: string, stat
   logger.warn(`[SDK] run ${status} with ${report.totalErrors} tracked error(s) across ${report.uniquePatterns} pattern(s) [${depthLabel}]${top ? ` — top: ${top}` : ''}`);
 }
 
+/**
+ * Capture how many researchers were planned/launched/failed for this run, BEFORE
+ * the caller's `finally` block frees the PiSessionState (endResearchSession) that
+ * getFailedResearchers()/getResearcherFailureReasons() read from. Best-effort:
+ * this is instrumentation only and must never affect the run's own result.
+ */
+async function captureResearcherOutcome(sessionId: string, researchId: string, snapshot: IMetricsSnapshot): Promise<ResearcherOutcome | null> {
+  try {
+    const planningService = await getService<IPlanningService>(ServiceNames.PLANNING, undefined, 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;
+  }
+}
+
 /**
  * Distilled, human-relevant stats from the most recent run (researchers launched,
  * searches, URLs analyzed/failed, tokens, cost, per-tool usage). Null if no run
@@ -744,7 +796,7 @@ export async function searchKnowledge(
   };
 }
 
-import { clearAllSessionState, endResearchSession } from './orchestration/session-state.ts';
+import { clearAllSessionState, endResearchSession, getFailedResearchers, getResearcherFailureReasons } from './orchestration/session-state.ts';
 import { shutdownManager } from './utils/shutdown-manager.ts';
 
 /**
@@ -833,6 +885,7 @@ async function _doShutdown(): Promise<void> {
   _lastResearchId = null;
   _lastRunSummary = null;
   _lastErrorReport = null;
+  _lastResearcherOutcome = null;
   // The module-level config cache survives the globals above. Without this, a
   // shutdown → env/config-file change → re-init cycle in one process silently
   // reuses the first init's config. (The CLI/skill are unaffected — they pass

package/src/youtube/index.ts

@@ -126,10 +126,11 @@ function formatResults(results: VideoTranscript[], rejected: string[]): string {
     // citation pipeline (parseCitations extracts URLs), so the transcript's
     // provenance would silently drop out of the final report's CITED LINKS.
     // The title/channel follows so the report names the real video, not a
-    // paraphrase (the watch URL alone is not human-identifiable).
-    if (r.title) {
-      md += `**Cite as:** ${r.url} — '${r.title}'${r.author ? ` by ${r.author}` : ''}\n`;
-    }
+    // paraphrase (the watch URL alone is not human-identifiable). Emit this line
+    // unconditionally — an untitled video still needs a parseable "Cite as" the
+    // model can copy verbatim; omitting the line entirely for untitled videos
+    // left them without any prompt-visible citation string to reuse.
+    md += `**Cite as:** ${r.url}${r.title ? ` — '${r.title}'${r.author ? ` by ${r.author}` : ''}` : ''}\n`;
     md += `\n${r.text}\n\n---\n\n`;
   }