@lincoln504/pi-research 1.0.3 → 1.0.5

package/dist/cli.mjs

@@ -3252,7 +3252,7 @@ function buildModelRegistry(apiKey, provider) {
       fs5.existsSync(modelsJsonPath) ? modelsJsonPath : void 0
     );
   }
-  if (fs5.existsSync(authPath)) {
+  if (fs5.existsSync(authPath) || fs5.existsSync(modelsJsonPath)) {
     const authStorage = AuthStorage.create(authPath);
     return ModelRegistry.create(
       authStorage,
@@ -3266,7 +3266,17 @@ function constructMinimalModel(provider, modelId, _apiKey) {
     provider,
     id: modelId,
     name: modelId,
-    api: provider === "openai" ? "openai-completions" : provider + "-conversations",
+    // Map to a REAL pi-ai api id — "<provider>-conversations" is not one, and a
+    // keyed no-registry setup would pass pre-flight then die on the first call.
+    // Unknown providers default to the OpenAI-compatible protocol, which is what
+    // virtually every third-party endpoint (openrouter, groq, cerebras, …) speaks.
+    api: {
+      openai: "openai-completions",
+      anthropic: "anthropic-messages",
+      google: "google-generative-ai",
+      gemini: "google-generative-ai",
+      mistral: "mistral-conversations"
+    }[provider] ?? "openai-completions",
     baseUrl: "",
     // Provider-specific base URLs are handled by pi-ai internal registry
     reasoning: false,
@@ -4702,9 +4712,6 @@ var init_store = __esm({
                   if (strategy !== "drop" && strategy !== "backup") {
                     logger.warn("[store] Falling back to backup strategy after migration failure");
                     await this.handleModelChange(storedModel || "unknown", this.options.modelName, "backup");
-                  } else if (strategy === "backup") {
-                    logger.warn("[store] Falling back to drop strategy after backup failure");
-                    await this.handleModelChange(storedModel || "unknown", this.options.modelName, "drop");
                   } else {
                     throw new Error(errorMsg, { cause: err });
                   }
@@ -4753,7 +4760,12 @@ var init_store = __esm({
         if (!this.table || !this.db) {
           throw new Error("Table not connected");
         }
-        const count = await this.table.countRows();
+        let count = -1;
+        try {
+          count = await this.table.countRows();
+        } catch (err) {
+          logger.warn(`[store] countRows failed before backup (continuing): ${err instanceof Error ? err.message : String(err)}`);
+        }
         this.table = null;
         const oldDir = path13.join(this.options.dbDir, `${this.tableName}.lance`);
         const backupDir = path13.join(this.options.dbDir, `${backupTableName}.lance`);
@@ -4768,8 +4780,8 @@ var init_store = __esm({
         }
         this.table = await this.createTable();
         await this.saveManifest();
-        logger.info(`[store] Migration complete: ${count} documents backed up, fresh table created with model ${newModel}`);
-        return { strategy: "backup", success: true, documentsProcessed: count };
+        logger.info(`[store] Migration complete: ${count >= 0 ? count : "unknown count of"} documents backed up, fresh table created with model ${newModel}`);
+        return { strategy: "backup", success: true, documentsProcessed: Math.max(0, count) };
       }
       async migrationDrop(_oldModel, newModel) {
         logger.warn(`[store] Dropping table and recreating with model ${newModel} (data will be lost)`);
@@ -9358,6 +9370,7 @@ init_constants();
 var sessionLinks = /* @__PURE__ */ new Map();
 var sessionScrapedContent = /* @__PURE__ */ new Map();
 var researcherScrapes = /* @__PURE__ */ new Map();
+var transcribedUrls = /* @__PURE__ */ new Map();
 var sessionTimestamps = /* @__PURE__ */ new Map();
 var SESSION_MAX_AGE_MS = 2 * 60 * 60 * 1e3;
 var MAX_CACHED_CONTENT_PER_SESSION = 500;
@@ -9373,6 +9386,7 @@ function startCleanupTimer() {
         sessionScrapedContent.delete(researchId);
         sessionTimestamps.delete(researchId);
         researcherScrapes.delete(researchId);
+        transcribedUrls.delete(researchId);
         cleaned++;
       }
     }
@@ -9410,6 +9424,17 @@ function registerScrapedLinks(researchId, links) {
 function getScrapedLinks(researchId) {
   return Array.from(sessionLinks.get(researchId) || []);
 }
+function registerTranscribedLinks(researchId, links) {
+  if (!transcribedUrls.has(researchId)) {
+    transcribedUrls.set(researchId, /* @__PURE__ */ new Set());
+  }
+  sessionTimestamps.set(researchId, Date.now());
+  const pool = transcribedUrls.get(researchId);
+  links.forEach((l) => pool.add(normalizeUrl(l)));
+}
+function isTranscribedLink(researchId, url) {
+  return transcribedUrls.get(researchId)?.has(normalizeUrl(url)) ?? false;
+}
 function deduplicateUrls(urls, researchId) {
   const pool = sessionLinks.get(researchId) || /* @__PURE__ */ new Set();
   const kept = [];
@@ -9429,6 +9454,7 @@ function cleanupSharedLinks(researchId) {
   sessionScrapedContent.delete(researchId);
   sessionTimestamps.delete(researchId);
   researcherScrapes.delete(researchId);
+  transcribedUrls.delete(researchId);
   logger.debug(`[Shared Links] Cleaned up session: ${researchId}`);
 }
 function clearAllSharedLinks() {
@@ -9440,6 +9466,7 @@ function clearAllSharedLinks() {
   sessionScrapedContent.clear();
   sessionTimestamps.clear();
   researcherScrapes.clear();
+  transcribedUrls.clear();
   logger.debug("[Shared Links] All global state cleared");
 }
 function registerResearcherScrapes(researchId, researcherId, urls) {
@@ -15699,6 +15726,48 @@ function decodeHtmlBody(bytes, contentTypeHeader) {
     return new TextDecoder("utf-8").decode(bytes);
   }
 }
+var BodyTooLargeError = class extends Error {
+  constructor(bytesRead, maxBytes) {
+    super(`Response body exceeded ${maxBytes} byte cap`);
+    this.bytesRead = bytesRead;
+    this.maxBytes = maxBytes;
+    this.name = "BodyTooLargeError";
+  }
+  bytesRead;
+  maxBytes;
+};
+async function readBodyCapped(response, maxBytes) {
+  const body = response.body;
+  if (!body || typeof body.getReader !== "function") {
+    return new Uint8Array(await response.arrayBuffer());
+  }
+  const reader = body.getReader();
+  const chunks = [];
+  let total = 0;
+  try {
+    for (; ; ) {
+      const { done, value } = await reader.read();
+      if (done) break;
+      if (value) {
+        total += value.byteLength;
+        if (total > maxBytes) throw new BodyTooLargeError(total, maxBytes);
+        chunks.push(value);
+      }
+    }
+  } finally {
+    try {
+      await reader.cancel();
+    } catch {
+    }
+  }
+  const out = new Uint8Array(total);
+  let offset = 0;
+  for (const c of chunks) {
+    out.set(c, offset);
+    offset += c.byteLength;
+  }
+  return out;
+}
 async function scrapeWithFetch(url, signal) {
   await validateUrlForSSRF(url);
   const dispatcher = await getSsrfSafeDispatcher();
@@ -15734,6 +15803,10 @@ async function scrapeWithFetch(url, signal) {
         if (!location) break;
         const resolved = new URL(location, currentUrl).href;
         await validateUrlForSSRF(resolved);
+        try {
+          await response.body?.cancel();
+        } catch {
+        }
         currentUrl = resolved;
         continue;
       }
@@ -15741,6 +15814,10 @@ async function scrapeWithFetch(url, signal) {
     }
     if (!response.ok) {
       metrics.increment("scrape_errors_total", 1, { error_type: "http_error", status_code: String(response.status) });
+      try {
+        await response.body?.cancel();
+      } catch {
+      }
       throw new Error(`HTTP ${response.status}`);
     }
     const contentType = response.headers.get("content-type") ?? "";
@@ -15753,24 +15830,62 @@ async function scrapeWithFetch(url, signal) {
           const sizeMB = Math.round(size / 1024 / 1024);
           logger.warn(`[Scrapers] PDF too large (Content-Length: ${sizeMB}MB, max 100MB), skipping`);
           metrics.increment("scrape_pdf_errors_total", 1, { error_type: "size_exceeded" });
+          try {
+            await response.body?.cancel();
+          } catch {
+          }
           throw new Error(`PDF too large (${sizeMB}MB, max 100MB)`);
         }
       } else if (size > MAX_HTML_SIZE) {
         const sizeMB = Math.round(size / 1024 / 1024);
         logger.warn(`[Scrapers] HTML response too large (Content-Length: ${sizeMB}MB, max 25MB), skipping`);
         metrics.increment("scrape_errors_total", 1, { error_type: "size_exceeded", content_type: contentType.split(";")[0] || "unknown" });
+        try {
+          await response.body?.cancel();
+        } catch {
+        }
         throw new Error(`HTML response too large (${sizeMB}MB, max 25MB)`);
       }
     }
     if (contentType.includes("application/pdf") || url.toLowerCase().endsWith(".pdf")) {
-      const buffer = await response.arrayBuffer();
-      const markdown2 = await extractPdfToMarkdown(new Uint8Array(buffer));
+      let pdfBytes;
+      try {
+        pdfBytes = await readBodyCapped(response, MAX_PDF_SIZE);
+      } catch (e) {
+        if (e instanceof BodyTooLargeError) {
+          const sizeMB = Math.round(e.bytesRead / 1024 / 1024);
+          logger.warn(`[Scrapers] PDF too large (streamed ${sizeMB}MB, max 100MB), skipping`);
+          metrics.increment("scrape_pdf_errors_total", 1, { error_type: "size_exceeded" });
+          throw new Error(`PDF too large (${sizeMB}MB, max 100MB)`, { cause: e });
+        }
+        throw e;
+      }
+      const markdown2 = await extractPdfToMarkdown(pdfBytes);
       validateContent("", markdown2, url);
       metrics.increment("scrape_operations_total", 1, { layer: "fetch", content_type: "pdf", status: "success" });
       metrics.observe("scrape_latency_ms", fetchDuration, { layer: "fetch", content_type: "pdf", status: "success" });
       return { source: "fetch", layer: "fetch", markdown: markdown2 };
     }
-    const bodyBytes = new Uint8Array(await response.arrayBuffer());
+    let bodyBytes;
+    try {
+      bodyBytes = await readBodyCapped(response, MAX_HTML_SIZE);
+    } catch (e) {
+      if (e instanceof BodyTooLargeError) {
+        const sizeMB = Math.round(e.bytesRead / 1024 / 1024);
+        logger.warn(`[Scrapers] HTML response too large (streamed ${sizeMB}MB, max 25MB), skipping`);
+        metrics.increment("scrape_errors_total", 1, { error_type: "size_exceeded", content_type: "html" });
+        errorTracker.trackError(new Error(`HTML response too large (${sizeMB}MB, max 25MB)`), {
+          component: "scrapers",
+          operation: "fetch",
+          url,
+          domain: extractDomain(url),
+          layer: "fetch",
+          contentType: "html"
+        });
+        throw new Error(`HTML response too large (${sizeMB}MB, max 25MB)`, { cause: e });
+      }
+      throw e;
+    }
     if (bodyBytes.length > MAX_HTML_SIZE) {
       const sizeMB = Math.round(bodyBytes.length / 1024 / 1024);
       logger.warn(`[Scrapers] HTML response too large (actual: ${sizeMB}MB, max 25MB), skipping`);
@@ -16468,6 +16583,8 @@ function handleFetchError(error) {
 }
 function handleResponseStatus(response) {
   if (!response.ok) {
+    void response.body?.cancel()?.catch(() => {
+    });
     if (response.status === 429) {
       throw new Error("NVD API rate limit exceeded (HTTP 429). Retrying with backoff...");
     }
@@ -16662,6 +16779,8 @@ async function fetchWithRetryImpl(url, options, signal) {
       async () => {
         const response = await fetch(url, options);
         if (!response.ok) {
+          void response.body?.cancel()?.catch(() => {
+          });
           const error = new Error(`HTTP ${response.status}: ${response.statusText}`);
           error.status = response.status;
           metrics.increment("cisa_kev_errors_total", 1, { endpoint, status_code: response.status.toString() });
@@ -17018,6 +17137,8 @@ async function searchGitHubAdvisories(terms, options) {
           signal: createTimeoutSignal(1e4, options?.signal)
         });
         if (!resp.ok) {
+          void resp.body?.cancel()?.catch(() => {
+          });
           if (resp.status === 404) {
             throw new Error(`Repository "${owner}/${name}" not found or no access to security advisories.`);
           }
@@ -17085,6 +17206,8 @@ async function searchGitHubAdvisories(terms, options) {
             signal: createTimeoutSignal(1e4, options?.signal)
           });
           if (!resp.ok) {
+            void resp.body?.cancel()?.catch(() => {
+            });
             if (resp.status === 404) {
               throw new Error("Advisory not found (HTTP 404)");
             }
@@ -17405,6 +17528,8 @@ async function fetchWithRetry2(url, options, signal) {
       async () => {
         const response = await fetch(url, options);
         if (!response.ok) {
+          void response.body?.cancel()?.catch(() => {
+          });
           const error = new Error(`HTTP ${response.status}: ${response.statusText}`);
           error.status = response.status;
           metrics.increment("osv_errors_total", 1, { endpoint, status_code: response.status.toString() });
@@ -19143,6 +19268,8 @@ async function fetchOne(session, videoId, contentToken, lang, timeoutMs, signal,
             headers: { "User-Agent": "Mozilla/5.0", "Accept-Language": lang }
           });
           if (!response.ok) {
+            void response.body?.cancel()?.catch(() => {
+            });
             throw new Error(`HTTP ${response.status} from timedtext endpoint`);
           }
           const body = await response.text();
@@ -19319,7 +19446,7 @@ function formatResults(results, rejected) {
     if (meta.length) md += `**${meta.join(" \xB7 ")}**
 `;
     if (r.title) {
-      md += `**Cite as:** '${r.title}'${r.author ? ` by ${r.author}` : ""}
+      md += `**Cite as:** ${r.url} \u2014 '${r.title}'${r.author ? ` by ${r.author}` : ""}
 `;
     }
     md += `
@@ -19378,7 +19505,7 @@ function createYoutubeTranscriptTool(options) {
       "You may call this tool only ONCE, so choose the videos carefully before calling.",
       "Pass full watch URLs, youtu.be links, or shorts/embed/live links. Non-YouTube links are ignored.",
       "Videos without captions, or that are private/age-restricted, are reported as unavailable \u2014 the rest still succeed.",
-      `When you cite a YouTube source in CITED LINKS, use the video's ACTUAL title and channel (both shown in this tool's output) as the description \u2014 e.g. "'<exact title>' by <channel>". Do NOT paraphrase or invent a title; the watch URL alone is not human-identifiable.`
+      `When you cite a YouTube source in CITED LINKS, the entry's link MUST be the video's watch URL (shown in this tool's output) \u2014 a title-only entry loses the source from the final report. Put the video's ACTUAL title and channel in the Description \u2014 e.g. "'<exact title>' by <channel>". Do NOT paraphrase or invent a title.`
     ],
     parameters: YoutubeParamsSchema,
     executionMode: "parallel",
@@ -19429,6 +19556,7 @@ function createYoutubeTranscriptTool(options) {
         });
         if (researchId && cachedUrls.length > 0) {
           registerScrapedLinks(researchId, cachedUrls);
+          registerTranscribedLinks(researchId, cachedUrls);
           options.updateGlobalLinks?.(cachedUrls);
           if (options.researcherId) {
             registerResearcherScrapes(researchId, options.researcherId, cachedUrls);
@@ -19812,6 +19940,7 @@ function getPiState(piSessionId) {
   if (!state) {
     state = {
       failures: /* @__PURE__ */ new Map(),
+      failureReasons: /* @__PURE__ */ new Map(),
       order: [],
       panels: /* @__PURE__ */ new Map(),
       aborts: /* @__PURE__ */ new Map(),
@@ -19883,6 +20012,7 @@ function refreshAllSessions(piSessionId) {
         for (const id of state.order) {
           if (!validIds.includes(id)) {
             state.failures.delete(id);
+            state.failureReasons.delete(id);
             state.panels.delete(id);
           }
         }
@@ -19914,6 +20044,7 @@ function endResearchSession(piSessionId, researchId) {
   const state = piSessions.get(sid);
   if (!state) return;
   state.failures.delete(researchId);
+  state.failureReasons.delete(researchId);
   state.panels.delete(researchId);
   state.aborts.delete(researchId);
   const index = state.order.indexOf(researchId);
@@ -19931,6 +20062,7 @@ function endResearchSession(piSessionId, researchId) {
       piSessions.delete(sid);
     } else {
       state.failures.clear();
+      state.failureReasons.clear();
       state.aborts.clear();
     }
   }
@@ -19952,12 +20084,23 @@ function clearAllSessionState() {
   clearAllSharedLinks();
   logger.log("[session-state] All session state cleared");
 }
-function recordResearcherFailure(piSessionId, researchId, researcherId) {
+function recordResearcherFailure(piSessionId, researchId, researcherId, reason) {
   const sid = normalizeSessionId(piSessionId);
   const state = getPiState(sid);
   const failures = state.failures.get(researchId) || [];
   failures.push(researcherId);
   state.failures.set(researchId, failures);
+  if (reason) {
+    const reasons = state.failureReasons.get(researchId) ?? /* @__PURE__ */ new Map();
+    if (!reasons.has(researcherId)) reasons.set(researcherId, reason);
+    state.failureReasons.set(researchId, reasons);
+  }
+}
+function getResearcherFailureReasons(piSessionId, researchId) {
+  const sid = normalizeSessionId(piSessionId);
+  const state = getPiState(sid);
+  const reasons = state.failureReasons.get(researchId);
+  return reasons ? Object.fromEntries(reasons) : {};
 }
 function getFailedResearchers(piSessionId, researchId) {
   const sid = normalizeSessionId(piSessionId);
@@ -19974,9 +20117,13 @@ function getResearchStopMessage(piSessionId, researchId) {
   const sid = normalizeSessionId(piSessionId);
   const failed = getFailedResearchers(sid, researchId);
   const count = failed.length;
+  const state = getPiState(sid);
+  const reasons = state.failureReasons.get(researchId);
+  const recorded = reasons && reasons.size > 0 ? ["Recorded errors:", ...[...reasons].map(([id, r]) => `\u2022 researcher ${id}: ${r}`), ""] : [];
   return [
     `Research stopped: ${count} researcher(s) did not return a usable report: ${failed.join(", ")}.`,
     "",
+    ...recorded,
     "Most likely cause \u2014 the research model could not produce grounded results:",
     '\u2022 Try a more capable research model. Very small or "thinking-only" models often',
     "  emit no final text after their tool calls, which fails every researcher.",
@@ -20026,7 +20173,7 @@ ${currentPlan.allQueries.map((q) => `- ${q}`).join("\n")}
   const researcherPromptTemplate = loadPrompt("researcher");
   if (initialLinks.length === 0 && historicalUrls.length === 0) {
     logger.warn(`[ResearcherExecutor] Researcher ${id} has no initial search results or historical links; skipping.`);
-    recordResearcherFailure(sessionId, researchId, id);
+    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;
@@ -20280,6 +20427,34 @@ init_constants();
 
 // src/orchestration/headless-observer.ts
 init_logger();
+function makeSafeObserver(observer) {
+  return new Proxy(observer, {
+    get(target, prop) {
+      let value;
+      try {
+        value = Reflect.get(target, prop, target);
+      } catch (err) {
+        logger.warn(`[observer] Ignored error reading observer.${String(prop)}:`, err);
+        return void 0;
+      }
+      if (typeof value !== "function") return value;
+      return (...args) => {
+        try {
+          const out = value.apply(target, args);
+          if (out && typeof out.then === "function") {
+            return out.catch((err) => {
+              logger.warn(`[observer] Ignored rejection from observer.${String(prop)}:`, err);
+            });
+          }
+          return out;
+        } catch (err) {
+          logger.warn(`[observer] Ignored error from observer.${String(prop)}:`, err);
+          return void 0;
+        }
+      };
+    }
+  });
+}
 var HeadlessObserver = class {
   constructor(options = {}) {
     this.options = options;
@@ -20369,9 +20544,9 @@ var QuickResearchOrchestrator = class {
     this.options = options;
     this.config = options.config || getConfig(options.ctx.cwd);
     if (options.observer && typeof options.observer.onProgress === "function" && !(options.observer instanceof HeadlessObserver)) {
-      this.observer = new HeadlessObserver(options.observer);
+      this.observer = makeSafeObserver(new HeadlessObserver(options.observer));
     } else {
-      this.observer = options.observer;
+      this.observer = options.observer ? makeSafeObserver(options.observer) : void 0;
     }
   }
   options;
@@ -20685,9 +20860,9 @@ var DeepResearchOrchestrator = class {
     this.options = options;
     this.config = options.config || getConfig(options.ctx.cwd);
     if (options.observer && typeof options.observer.onProgress === "function" && !(options.observer instanceof HeadlessObserver)) {
-      this.observer = new HeadlessObserver(options.observer);
+      this.observer = makeSafeObserver(new HeadlessObserver(options.observer));
     } else {
-      this.observer = options.observer;
+      this.observer = options.observer ? makeSafeObserver(options.observer) : void 0;
     }
     if (options.orchestrationService) {
       this.orchestrationService = options.orchestrationService;
@@ -20960,13 +21135,22 @@ var DeepResearchOrchestrator = class {
         observer?.onEvaluationDecision?.("synthesize", finalReport, maxRounds);
       }
       let result = finalReport.content || "";
+      const synthesisCheckService = await getService(ServiceNames.RESEARCH_SYNTHESIS_SERVICE, ctx, container);
+      const hasReports = synthesisCheckService.hasReports(researchId);
+      const failedIds = getFailedResearchers(this.options.sessionId, researchId);
+      if (!hasReports && failedIds.length > 0) {
+        const reasons = getResearcherFailureReasons(this.options.sessionId, researchId);
+        const causes = failedIds.map((id) => `researcher ${id}: ${reasons[id] ?? "no usable report"}`).join("; ");
+        throw new Error(
+          `Research produced no report \u2014 no source material was collected. Causes: ${causes}`
+        );
+      }
       if (!result.trim()) {
-        const synthesisService2 = await getService(ServiceNames.RESEARCH_SYNTHESIS_SERVICE, ctx, container);
-        if (synthesisService2.hasReports(researchId)) {
-          logger.warn(`[DeepOrchestrator] LLM returned empty synthesis for ${researchId}, building fallback from ${synthesisService2.getReportCount(researchId)} reports`);
-          result = synthesisService2.buildFallbackSynthesis(researchId, this.currentRound);
+        if (hasReports) {
+          logger.warn(`[DeepOrchestrator] LLM returned empty synthesis for ${researchId}, building fallback from ${synthesisCheckService.getReportCount(researchId)} reports`);
+          result = synthesisCheckService.buildFallbackSynthesis(researchId, this.currentRound);
         } else {
-          result = "Research completed but no summary was generated.";
+          throw new Error("Research produced no report \u2014 no source material was collected.");
         }
       }
       try {
@@ -21268,7 +21452,7 @@ var ResearchOrchestrationService = class {
             logger.debug(`[ResearchOrchestrationService] Researcher ${id} cancelled (aborted).`);
           } else {
             logger.error(`[ResearchOrchestrationService] Researcher ${id} failed: ${errMsg}`);
-            recordResearcherFailure(sessionId, researchId, id);
+            recordResearcherFailure(sessionId, researchId, id, errMsg);
             observer?.onResearcherFailure?.(id, errMsg);
           }
         }
@@ -21697,9 +21881,14 @@ Research performed using ${modelId}`;
     if (globalCitations.length === 0) {
       const scraped = getScrapedLinks(sessionId);
       if (scraped.length > 0) {
-        globalCitations = scraped.map((url, i) => ({ id: i + 1, url, description: "", source: "Scrape" }));
+        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 provenance.`
+          `[ResearchSynthesisService] No citations parsed from reports; rebuilt ${scraped.length} source(s) from scrape/transcript provenance.`
         );
       }
     }
@@ -22000,6 +22189,10 @@ async function _doInit(options = {}) {
   }
   globalApiKey = options.apiKey || process.env["PI_RESEARCH_API_KEY"];
   let parsedProvider = options.provider || process.env["PI_RESEARCH_PROVIDER"];
+  if (options.model) {
+    const explicit = typeof options.model === "string" ? options.model : `${options.model.provider}/${options.model.id}`;
+    globalConfig = { ...globalConfig, RESEARCH_MODEL: explicit };
+  }
   const effectiveModel = options.model ?? globalConfig.RESEARCH_MODEL;
   if (!parsedProvider && effectiveModel) {
     if (typeof effectiveModel === "string") {
@@ -22229,6 +22422,7 @@ async function _doShutdown() {
   _lastResearchId = null;
   _lastRunSummary = null;
   _lastErrorReport = null;
+  resetConfig();
   _removeSignalHandlers();
   if (errors.length > 0) {
     throw new AggregateError(errors, `${errors.length} error(s) during SDK shutdown`);
@@ -22475,6 +22669,7 @@ Total cost: ${costStr}`;
 
 // src/cli.ts
 init_config();
+init_model_registry_factory();
 import { getAgentDir as getAgentDir2 } from "@earendil-works/pi-coding-agent";
 function readPkgVersion() {
   try {
@@ -22593,7 +22788,16 @@ function fileExists(p) {
     return false;
   }
 }
-function detectCredentials() {
+function piKeysAvailable(piAuthPresent, provider) {
+  try {
+    const available = safeGetAvailable(buildModelRegistry(void 0, void 0));
+    if (!provider) return available.length > 0;
+    return available.some((m) => m.provider === provider);
+  } catch {
+    return piAuthPresent;
+  }
+}
+function detectCredentials(explicitModel) {
   const paths = resolvedConfigPaths();
   const piAuthPresent = fileExists(paths.piAuth);
   const piModelsPresent = fileExists(paths.piModels);
@@ -22601,9 +22805,10 @@ function detectCredentials() {
   const providerEnv = process.env["PI_RESEARCH_PROVIDER"];
   const modelEnv = process.env["PI_RESEARCH_MODEL"];
   const modelConfig = getConfig(process.cwd(), "cli").RESEARCH_MODEL;
-  const model = modelEnv ?? modelConfig;
-  const modelFrom = modelEnv ? "PI_RESEARCH_MODEL" : modelConfig ? "config.env" : "unset";
+  const model = explicitModel ?? modelEnv ?? modelConfig;
+  const modelFrom = explicitModel ? "--model" : modelEnv ? "PI_RESEARCH_MODEL" : modelConfig ? "config.env" : "unset";
   const provider = providerEnv ?? (model && model.includes("/") ? model.slice(0, model.indexOf("/")) : void 0);
+  const piKeysUsable = piKeysAvailable(piAuthPresent, provider);
   if (apiKey) {
     if (!provider) {
       return {
@@ -22626,7 +22831,7 @@ function detectCredentials() {
         modelFrom,
         piAuthPresent,
         piModelsPresent,
-        problem: 'PI_RESEARCH_API_KEY is set but no model is configured. Set PI_RESEARCH_MODEL to a "provider/model-id" (e.g. openai/gpt-4o).'
+        problem: 'PI_RESEARCH_API_KEY is set but no model is configured. Set PI_RESEARCH_MODEL to a "provider/model-id" (e.g. openai/gpt-4o), or pass --model <provider/id> for a single run.'
       };
     }
     return {
@@ -22639,7 +22844,7 @@ function detectCredentials() {
       piModelsPresent
     };
   }
-  if (piAuthPresent) {
+  if (piKeysUsable) {
     if (!model) {
       return {
         source: "pi-config",
@@ -22649,13 +22854,13 @@ function detectCredentials() {
         modelFrom,
         piAuthPresent,
         piModelsPresent,
-        problem: 'pi credentials were found (auth.json), but no research model is configured. The standalone CLI / agent skill run only on an explicitly configured model \u2014 they do not follow the model selected inside the pi extension. Set PI_RESEARCH_MODEL to a "provider/model-id" (in the environment, or in config.env / cli.env below).'
+        problem: `pi credentials were found (in pi's configuration), but no research model is configured. The standalone CLI / agent skill run only on an explicitly configured model \u2014 they do not follow the model selected inside the pi extension. Set PI_RESEARCH_MODEL to a "provider/model-id" (in the environment, or in config.env / cli.env below), or pass --model <provider/id> for a single run.`
       };
     }
     return {
       source: "pi-config",
       apiKeyConfigured: true,
-      // key lives in auth.json; SDK reads it
+      // key lives in pi's configuration; the SDK reads it at call time
       provider,
       model,
       modelFrom,
@@ -22671,7 +22876,7 @@ function detectCredentials() {
     modelFrom,
     piAuthPresent,
     piModelsPresent,
-    problem: "No model or API key is configured for pi-research. Provide credentials via environment variables (PI_RESEARCH_API_KEY + PI_RESEARCH_PROVIDER + PI_RESEARCH_MODEL) or, if you use pi, via ~/.pi/agent/auth.json."
+    problem: "No model or API key is configured for pi-research. Provide credentials via environment variables (PI_RESEARCH_API_KEY + PI_RESEARCH_PROVIDER + PI_RESEARCH_MODEL) or, if you use pi, via pi's configuration (a provider entry in ~/.pi/agent/auth.json, or a per-provider apiKey in ~/.pi/agent/models.json)."
   };
 }
 function configBlock(det, extraNote) {
@@ -22689,13 +22894,13 @@ function configBlock(det, extraNote) {
   lines.push(`  \u2022 api key configured: ${det.apiKeyConfigured}`);
   lines.push(`  \u2022 provider:           ${det.provider ?? "(unset \u2014 inferred from a provider/model-id model)"}`);
   lines.push(`  \u2022 model:              ${det.model ? `${det.model}  [from: ${det.modelFrom}]` : "(not set \u2014 set PI_RESEARCH_MODEL, required)"}`);
-  lines.push(`  \u2022 pi auth.json:       ${det.piAuthPresent ? "present" : "absent"}`);
-  lines.push(`  \u2022 pi models.json:     ${det.piModelsPresent ? "present" : "absent"}`);
+  lines.push(`  \u2022 pi config (auth.json):   ${det.piAuthPresent ? "present" : "absent"}`);
+  lines.push(`  \u2022 pi config (models.json): ${det.piModelsPresent ? "present" : "absent"}`);
   if (extraNote) lines.push(`  \u2022 note:               ${extraNote}`);
   return lines.join("\n");
 }
 async function cmdResearch(args) {
-  const det = detectCredentials();
+  const det = detectCredentials(args.model);
   if (det.problem) {
     if (args.json) toStdout(pretty({ ok: false, error: det.problem, exitCode: EXIT.CONFIG }));
     else toStderr(`
@@ -22717,7 +22922,7 @@ Error: ${vmsg}
     return EXIT.USAGE;
   }
   const depth = args.depth ?? getConfig(process.cwd(), "cli").DEFAULT_RESEARCH_DEPTH;
-  const runModel = args.model ?? det.model;
+  const runModel = det.model;
   toStderr(`[pi-research] starting research (depth ${depth})${runModel ? ` with ${runModel}` : ""}\u2026
 `);
   const observer = makeProgressObserver();
@@ -23035,7 +23240,7 @@ function reportError(err, what, json) {
   const lower = msg2.toLowerCase();
   const isConfigError = lower.includes("no llm model available") || lower.includes("not found in pi") || lower.includes("no api key") || lower.includes("provider must be specified") || lower.includes("invalid model string") || lower.includes("authentication") || lower.includes("unauthorized") || lower.includes("api key");
   const isRateLimit = lower.includes("429") || lower.includes("rate limit") || lower.includes("too many requests");
-  const exitCode = isConfigError ? EXIT.CONFIG : EXIT.SOFTWARE;
+  const exitCode = isConfigError && !isRateLimit ? EXIT.CONFIG : EXIT.SOFTWARE;
   if (json) {
     const payload = { ok: false, error: msg2, exitCode };
     if (process.env["PI_RESEARCH_DEBUG"] === "true" && err instanceof Error && err.stack) {
@@ -23044,18 +23249,18 @@ function reportError(err, what, json) {
     toStdout(pretty(payload));
     return exitCode;
   }
-  if (isConfigError) {
+  if (isRateLimit) {
     toStderr(`
-Error: pi-research ${what} failed: ${msg2}
-
-${configBlock(detectCredentials())}
+Error: pi-research ${what} halted: provider rate limit reached. Wait a moment and retry.
+  ${msg2}
 `);
     return exitCode;
   }
-  if (isRateLimit) {
+  if (isConfigError) {
     toStderr(`
-Error: pi-research ${what} halted: provider rate limit reached. Wait a moment and retry.
-  ${msg2}
+Error: pi-research ${what} failed: ${msg2}
+
+${configBlock(detectCredentials())}
 `);
     return exitCode;
   }
@@ -23092,7 +23297,7 @@ USAGE
 COMMANDS
   research  "<query>"            Run multi-agent web research (default depth: 1).
     --depth <0-3>                0 = quick, 1 = normal (default), 2 = deep, 3 = ultra.
-    --model <provider/id>        Override the model for this run.
+    --model <provider/id>        Model for this run (outranks PI_RESEARCH_MODEL; satisfies the required-model check).
     --exclude-tools <a,b>        Disable internal tools (e.g. security_search,stackexchange).
     --initial-links <url ...>    Seed URLs to investigate first; requires a query (-- ends options).
     --config <path>              Use this config file instead of the base config.env.
@@ -23129,9 +23334,9 @@ CONFIGURE
     pi config (keys):    ${p.piAuth}
     pi config (models):  ${p.piModels}
 
-  A model is REQUIRED: set PI_RESEARCH_MODEL to a "provider/model-id". This CLI and
-  the agent skill run only on that configured model \u2014 they do not follow the model
-  selected inside the pi extension.
+  A model is REQUIRED: set PI_RESEARCH_MODEL to a "provider/model-id" (or pass
+  --model per run). This CLI and the agent skill run only on that configured
+  model \u2014 they do not follow the model selected inside the pi extension.
 
   The pi extension has its own optional overlay file:
     pi extension: ${p.piIfaceEnv}