@lincoln504/pi-research 1.0.6 → 1.0.9

package/src/core/llm/model-registry-factory.ts

@@ -8,7 +8,8 @@
  * Previously this logic was duplicated (#29) — any bug fix now updates both paths.
  */
 
-import { AuthStorage, ModelRegistry, getAgentDir } from '@earendil-works/pi-coding-agent';
+import { ModelRegistry, ModelRuntime, getAgentDir } from '@earendil-works/pi-coding-agent';
+import { InMemoryCredentialStore } from '@earendil-works/pi-ai';
 import type { Model } from '@earendil-works/pi-ai';
 import * as path from 'node:path';
 import * as fs from 'node:fs';
@@ -103,42 +104,93 @@ function buildHeaders(provider?: string): Record<string, string> {
 /**
  * Create a ModelRegistry with the given credentials.
  *
+ * pi 0.80.8 replaced `AuthStorage`/`ModelRegistry.create()` with the async
+ * `ModelRuntime`: `ModelRegistry` is now a SYNCHRONOUS compatibility facade that
+ * wraps a `ModelRuntime` and still exposes `getAll`/`getAvailable`/`find`/
+ * `getApiKeyAndHeaders` — so every consumer of the registry (resolveModel,
+ * safeGet*, the research-model resolver) stays synchronous. Only this factory
+ * became async (constructing the ModelRuntime is inherently async) and its two
+ * callers await it. Mirrors how pi itself builds a registry
+ * (`sdk.js`: `await ModelRuntime.create({ authPath, modelsPath })`).
+ *
  * @param apiKey  - Optional explicit API key
  * @param provider - Optional provider name to key the API key under
  * @returns A configured ModelRegistry
  */
-export function buildModelRegistry(apiKey?: string, provider?: string): ModelRegistry {
+export async function buildModelRegistry(apiKey?: string, provider?: string): Promise<ModelRegistry> {
   const agentDir = getAgentDir();
   const modelsJsonPath = path.join(agentDir, 'models.json');
   const authPath = path.join(agentDir, 'auth.json');
+  const hasModels = fs.existsSync(modelsJsonPath);
+  const hasAuth = fs.existsSync(authPath);
+
+  // Build the runtime from the user's pi config (models.json + auth.json) when
+  // EITHER file is present, otherwise a bare runtime that reads env-var keys and
+  // built-in providers. allowModelNetwork:false preserves the prior behavior of
+  // NOT doing a network model-catalog refresh at construction (the old
+  // ModelRegistry.create only read the local files). Env provider keys
+  // (e.g. OPENAI_API_KEY) are resolved via pi-ai's provider auth CONTEXT, not the
+  // credential store, so they are honored in every branch below; embedded
+  // models.json apiKeys likewise — auth.json presence must not gate models.json.
+  //
+  // When auth.json does NOT exist, an explicit in-memory credential store is
+  // passed instead of letting ModelRuntime default to the file at authPath:
+  // AuthStorage's file backend CREATES ~/.pi/agent/ and an empty auth.json as a
+  // construction side effect (mkdir+write). Without this, every CLI invocation —
+  // including read-only ones like `status` — would silently create a pi config
+  // dir on machines that never installed pi, and would hard-fail in read-only-
+  // $HOME environments (containers/CI) where the old in-memory path needed no
+  // filesystem write access at all.
+  const runtime = await ModelRuntime.create({
+    authPath: hasAuth ? authPath : undefined,
+    credentials: hasAuth ? undefined : new InMemoryCredentialStore(),
+    modelsPath: hasModels ? modelsJsonPath : null,
+    allowModelNetwork: false,
+  });
 
+  // Explicit key: seed it on the runtime after construction. NOTE: unlike the old
+  // AuthStorage.inMemory({ [provider]: ... }) seeding, this MERGES — the explicit
+  // key wins for its own provider (runtime overrides are checked first), but any
+  // providers already configured in auth.json remain visible in getAvailable().
+  // That broadening is acceptable because explicit-key flows always pair the key
+  // with an explicit model (enforced in cli.ts pre-flight), so resolution never
+  // falls back to "first available".
   if (apiKey && provider) {
-    // Explicit key: seed InMemory storage under the correct provider name.
-    const authStorage = AuthStorage.inMemory({
-      [provider]: { type: 'api_key', key: apiKey },
-    });
-    return ModelRegistry.create(
-      authStorage,
-      fs.existsSync(modelsJsonPath) ? modelsJsonPath : undefined,
-    );
+    // allowNetwork:false is REQUIRED here, not just consistent with create():
+    // setRuntimeApiKey triggers a model-catalog refresh for the newly configured
+    // provider, and its default options open live catalog connections — verified
+    // to hang indefinitely (no timeout at this layer) in network-restricted
+    // environments, which would wedge every explicit-API-key pre-flight.
+    await runtime.setRuntimeApiKey(provider, apiKey, { allowNetwork: false });
   }
 
-  // No explicit key: use the user's pi configuration when EITHER file exists.
-  // ModelRegistry.create() reads embedded apiKeys from models.json providers
-  // directly (via providerRequestConfigs), so custom providers with embedded
-  // keys work with no auth.json at all — auth.json presence must not gate
-  // models.json (AuthStorage.create tolerates a missing file). Env provider
-  // keys (e.g. OPENAI_API_KEY) are honored by AuthStorage in every branch.
-  if (fs.existsSync(authPath) || fs.existsSync(modelsJsonPath)) {
-    const authStorage = AuthStorage.create(authPath);
-    return ModelRegistry.create(
-      authStorage,
-      fs.existsSync(modelsJsonPath) ? modelsJsonPath : undefined,
-    );
-  }
+  // The sync facade all our resolvers consume. getAvailable()/getApiKeyAndHeaders()
+  // read a cached snapshot populated by create(), so the sync reads below work
+  // without further awaits.
+  const registry = new ModelRegistry(runtime);
+  registryRuntimes.set(registry, runtime);
+  return registry;
+}
 
-  // Last resort: in-memory with nothing — will fail at LLM call time with actionable error
-  return ModelRegistry.inMemory(AuthStorage.inMemory());
+/**
+ * The ModelRuntime backing each registry this factory built. Researcher sessions
+ * must be created with `modelRuntime` (pi 0.80.8+ replaced the old
+ * `modelRegistry` session option): without it, createAgentSession() builds its
+ * OWN runtime from the default ~/.pi/agent paths, which never sees an explicit
+ * API key seeded via setRuntimeApiKey above — standalone PI_RESEARCH_API_KEY
+ * users with no (or a different-provider) auth.json would pass pre-flight and
+ * then fail auth on every researcher LLM call.
+ */
+const registryRuntimes = new WeakMap<ModelRegistry, ModelRuntime>();
+
+/**
+ * Return the ModelRuntime behind a registry built by {@link buildModelRegistry},
+ * or undefined for registries built elsewhere (e.g. the pi host's own
+ * ExtensionContext.modelRegistry — for those, createAgentSession()'s default
+ * runtime construction from the host's agent dir is exactly right).
+ */
+export function getRuntimeForRegistry(registry: unknown): ModelRuntime | undefined {
+  return registry instanceof Object ? registryRuntimes.get(registry as ModelRegistry) : undefined;
 }
 
 /**

package/src/index.ts

@@ -53,6 +53,8 @@ export {
   getLastRunSummary,
   getLastErrorReport,
   getLastRunStats,
+  getLastResearcherOutcome,
+  type ResearcherOutcome,
   getSessionMetrics,
   getResearchHealth,
   runQuickResearch,
@@ -88,10 +90,14 @@ function extractResultText(result: AgentToolResult<unknown>): string {
  * Pi Research Extension
  */
 export default async function (pi: ExtensionAPI) {
-  // Runtime version check — must match the @earendil-works/* dependency minimum (>=0.80.2).
-  // 0.80.2 is the floor because the AuthStorage credential discriminator pi-research
-  // passes (`type: 'api_key'`, model-registry-factory.ts) only became correct in 0.80.2
-  // (it was `api-key` before); the pi-ai `/compat` entrypoint also exists from 0.80.0.
+  // Runtime version check — must match the @earendil-works/* dependency minimum (>=0.80.8).
+  // 0.80.8 is the floor because pi 0.80.8 introduced ModelRuntime and removed
+  // AuthStorage/ModelRegistry.create(); buildModelRegistry (model-registry-factory.ts)
+  // unconditionally calls ModelRuntime.create(), and createAgentSession() is invoked
+  // without the removed `modelRegistry` option (researcher.ts), relying on the
+  // 0.80.8+ host auto-building its ModelRuntime. This in-host check is the real
+  // enforcement point: when running as an extension the host's version is NOT
+  // constrained by npm's resolution of our own package.json range.
   const versionParts = PI_VERSION.split('.').map(Number);
   const major = versionParts[0] ?? 0;
   const minor = versionParts[1] ?? 0;
@@ -102,7 +108,7 @@ export default async function (pi: ExtensionAPI) {
       `Please ensure pi-coding-agent is installed correctly.`,
     );
   }
-  const minMajor = 0, minMinor = 80, minPatch = 2;
+  const minMajor = 0, minMinor = 80, minPatch = 8;
   const tooOld = major < minMajor
     || (major === minMajor && minor < minMinor)
     || (major === minMajor && minor === minMinor && patch < minPatch);

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) */
@@ -2276,9 +2278,13 @@ var ConfigSchema = Type.Object({
    *  never killed before it has used its full nav budget plus time waiting in the queue.
    *  (default: 10000) */
   BROWSER_TASK_TIMEOUT_MS: Type.Number({ minimum: 2e3, maximum: 12e4, default: 1e4 }),
-  /** Timeout for coordinator/evaluator/repair/knowledge LLM calls in ms (default: 300000 = 5 min, range: 60s-600s).
-   *  Not exposed in TUI — controlled via PI_RESEARCH_LLM_TIMEOUT_MS env var. */
-  LLM_TIMEOUT_MS: Type.Number({ minimum: 6e4, maximum: 6e5, default: 3e5 }),
+  /** Timeout for coordinator/evaluator/repair/knowledge LLM calls in ms (default: 300000 = 5 min, range: 60s-30min).
+   *  Not exposed in TUI — controlled via PI_RESEARCH_LLM_TIMEOUT_MS env var.
+   *  Ceiling raised to 30min (matching RESEARCHER_TIMEOUT_MS): a slow model on a
+   *  large-context synthesis/plan call can legitimately run >10min, and the old
+   *  600000 ceiling silently clamped an explicit PI_RESEARCH_LLM_TIMEOUT_MS
+   *  (e.g. 900000), causing those calls to time out mid-generation. */
+  LLM_TIMEOUT_MS: Type.Number({ minimum: 6e4, maximum: 18e5, default: 3e5 }),
   /** Chain-of-thought "thinking" level for the engine's own LLM calls (coordinator,
    *  evaluator, synthesis, JSON-repair, knowledge extraction) AND the researcher
    *  sub-agents. Default 'off': these calls emit structured JSON / cited reports, not

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/researcher.ts

@@ -22,6 +22,7 @@ import type { Config } from '../config.ts';
 import { logger } from '../logger.ts';
 
 import { resolveResearchModel } from '../core/llm/research-model-resolver.ts';
+import { getRuntimeForRegistry } from '../core/llm/model-registry-factory.ts';
 
 export interface CreateResearcherSessionOptions {
   cwd: string;
@@ -137,7 +138,17 @@ export async function createResearcherSession(options: CreateResearcherSessionOp
       sessionManager: SessionManager.inMemory(), // Each researcher gets its own isolated session
       settingsManager: researcherSettings,
       model: modelToUse,
-      modelRegistry,
+      // pi 0.80.8 replaced the SDK's `modelRegistry`/`authStorage` session options
+      // with the async `modelRuntime`. Pass the runtime backing OUR registry when
+      // this run built one (standalone CLI/SDK): it carries any explicit API key
+      // seeded via setRuntimeApiKey, which the session's own default runtime
+      // (auto-built from ~/.pi/agent/{auth,models}.json) would never see — without
+      // this, standalone PI_RESEARCH_API_KEY users fail auth on every researcher
+      // LLM call despite passing pre-flight. For registries we did NOT build
+      // (the pi host's ExtensionContext.modelRegistry), this resolves to
+      // undefined and the host auto-builds from its own agent dir — correct
+      // in-host, where auth lives in the host's config.
+      modelRuntime: getRuntimeForRegistry(modelRegistry),
       resourceLoader: makeResourceLoader(systemPrompt),
       // Thinking/reasoning is disabled for researcher agents: they do retrieval and
       // synthesis from scraped pages, not open-ended reasoning. Keeping it off reduces

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.