@lincoln504/pi-research 1.4.3 → 1.5.0

package/README.md

@@ -64,7 +64,7 @@ Three depth levels (normal, deep, ultra) set the team size and number of rounds.
 ### Why pi-research
 
 - **No quota and no monthly fee.** Most AI search providers cap free searches and then charge, with results served from their index on their servers. pi-research searches and scrapes locally through DuckDuckGo in a stealth browser.
-- **You own your index.** Every finding is written to a local [LanceDB](https://lancedb.com) knowledge store that seeds future runs, so repeat questions get faster and cheaper answers.
+- **You own your index.** Every finding can be saved to a local [LanceDB](https://lancedb.com) knowledge store that seeds future runs, so repeat questions get faster and cheaper answers.
 - **Cited reports rather than raw dumps.** You get one sourced Markdown report instead of raw web content pasted into the conversation. Context efficient and easy to verify.
 - **Read-only by design.** The research agent cannot run shell commands or write, edit, or delete anything. It can read files, so treat it as you would any read-only agent with access to your machine.
 - **Search a little or a lot.** Depth levels span a quick pass to a large-scale investigation.

package/dist/cli.mjs

@@ -2643,10 +2643,10 @@ function loadEnvFiles(cwd, iface) {
     try {
       logger.warn(`[config] WARNING: .pi-research.env files are deprecated. Settings will be auto-migrated to the centralized registry. Remove ${legacyPath} after migration.`);
       legacyEnv = parseDotEnv(fs5.readFileSync(legacyPath, "utf-8"));
-      Object.assign(merged, legacyEnv);
       const legacyLocal = Object.fromEntries(
         Object.entries(legacyEnv).filter(([k]) => LOCAL_SCOPE_KEYS.has(k))
       );
+      Object.assign(merged, legacyLocal);
       const existingLocal = Object.fromEntries(
         Object.entries(findRegistryEntry(registry, normalizedCwd) ?? {}).filter(([k]) => LOCAL_SCOPE_KEYS.has(k))
       );
@@ -2676,7 +2676,10 @@ function loadEnvFiles(cwd, iface) {
       }
     }
   } else if (Object.keys(merged).length === 0 && !fs5.existsSync(legacyPath) && !fs5.existsSync(globalPath)) {
-    logger.warn(`[config] No configuration found for workspace: ${cwd}. Using code defaults. Run /research-config to configure.`);
+    if (!warnedMissingConfigWorkspaces.has(normalizedCwd)) {
+      warnedMissingConfigWorkspaces.add(normalizedCwd);
+      logger.warn(`[config] No configuration found for workspace: ${cwd}. Using code defaults. Run /research-config to configure.`);
+    }
   }
   warnLegacyEnvVarsOnce(merged);
   return merged;
@@ -2965,7 +2968,7 @@ function parseEnvEnum(env, key, allowed, def) {
   logger.warn(`[config] Invalid ${key}="${raw}" (expected one of: ${allowed.join(", ")}). Using default "${def}".`);
   return def;
 }
-var ConfigSchema, DEFAULTS, LOCAL_SCOPE_KEYS, USER_MIGRATION_KEYS, RECLAIM_FILE_SWEEP_AGE_MS, LEGACY_ENV_VARS, warnedLegacyEnvVars, configCache;
+var ConfigSchema, DEFAULTS, LOCAL_SCOPE_KEYS, USER_MIGRATION_KEYS, RECLAIM_FILE_SWEEP_AGE_MS, LEGACY_ENV_VARS, warnedLegacyEnvVars, warnedMissingConfigWorkspaces, configCache;
 var init_config = __esm({
   "src/config.ts"() {
     "use strict";
@@ -3184,6 +3187,7 @@ var init_config = __esm({
       PROXY_URL: "no longer read \u2014 the SearXNG proxy path was removed in v1.0.0 and searches/scrapes connect directly"
     };
     warnedLegacyEnvVars = false;
+    warnedMissingConfigWorkspaces = /* @__PURE__ */ new Set();
     configCache = /* @__PURE__ */ new Map();
   }
 });
@@ -3196,10 +3200,11 @@ function getMaxGatheringCalls(config) {
     return MAX_GATHERING_CALLS;
   }
 }
-function getMaxScrapeBatches(config) {
+function getMaxScrapeBatches(config, cachingActive = false) {
   try {
     const batches = (config || getConfig()).MAX_SCRAPE_BATCHES;
-    return batches === 0 || batches > 99 ? 999999 : batches;
+    if (batches === 0 || batches > 99) return 999999;
+    return cachingActive ? Math.min(batches + 1, 99) : batches;
   } catch {
     return 2;
   }
@@ -5506,20 +5511,37 @@ var init_embedding_server = __esm({
         });
       }
       /**
-       * Resolve once no native call is in flight. Used by EmbeddingServer.shutdown()
-       * to wait out a still-running inference before disposing the pipeline —
-       * without this, disposal could run concurrently with a legitimately slow (not
-       * hung) embed/embedMany call on the same re-entrant-locked GPU context, the
-       * exact native-segfault class this queue exists to prevent. No timeout: a
-       * promise that truly never settles is already an accepted, pre-existing
-       * leak-to-process-exit scenario elsewhere in this class (see the poison path's
+       * Resolve once no native call is in flight AND no queued task is still due
+       * to run. Used by EmbeddingServer.shutdown() to wait out a still-running
+       * inference before disposing the pipeline — without this, disposal could
+       * run concurrently with a legitimately slow (not hung) embed/embedMany call
+       * on the same re-entrant-locked GPU context, the exact native-segfault
+       * class this queue exists to prevent. No timeout: a promise that truly
+       * never settles is already an accepted, pre-existing leak-to-process-exit
+       * scenario elsewhere in this class (see the poison path's
        * disposeEmbedder=false handling) — better to leak than risk concurrent
        * native access.
+       *
+       * Checking only `currentWork` is NOT enough with a second task already
+       * queued: a task's `run()` clears `currentWork` to null in its `finally`
+       * (once its native call has settled), and `pump()` only claims it again for
+       * the next task on a LATER microtask tick, once `run()` for the current
+       * task has fully unwound and `await entry.run()` resumes. If a caller's own
+       * check happens to land in that gap, `currentWork` reads as null even
+       * though a second native call is about to start (or a queue in the process
+       * of unwinding to its next task hasn't reached it yet) — exactly the window
+       * disposal must not run in. `running` stays true for the queue's entire
+       * drain, across every task in `tasks`, not just the current one, so it has
+       * no equivalent gap and closes this one.
        */
       async waitForIdle() {
-        while (this.currentWork) {
-          await this.currentWork.catch(() => {
-          });
+        while (this.currentWork || this.running) {
+          if (this.currentWork) {
+            await this.currentWork.catch(() => {
+            });
+          } else {
+            await Promise.resolve();
+          }
         }
       }
       poison(err) {
@@ -7683,10 +7705,31 @@ var init_store = __esm({
               this.table = await this.db.openTable(this.tableName);
             } else {
               logger.error("[store] Failed to persist canonical table name after rename \u2014 reverting to keep manifest and disk in sync.");
-              await fsPromises.rename(canonicalDir, tempDir);
-              this.tableName = tempTableName;
-              this.table = await this.db.openTable(this.tableName);
-              logger.info(`[store] Migrated data remains safe and accessible as ${tempTableName}; canonical rename deferred to a future successful manifest save.`);
+              try {
+                await fsPromises.rename(canonicalDir, tempDir);
+                this.tableName = tempTableName;
+                this.table = await this.db.openTable(this.tableName);
+                logger.info(`[store] Migrated data remains safe and accessible as ${tempTableName}; canonical rename deferred to a future successful manifest save.`);
+              } catch (revertErr) {
+                logger.error(`[store] Revert rename also failed; data remains on disk at ${canonicalDir}: ${revertErr}`);
+                this.tableName = canonicalName;
+                let reopened = false;
+                try {
+                  this.table = await this.db.openTable(this.tableName);
+                  reopened = true;
+                } catch (openErr) {
+                  logger.error(`[store] CRITICAL: could not reopen the table at '${canonicalName}' after a failed rename revert (${openErr}). Data should still be intact on disk at ${canonicalDir}, but this process has no working table handle for it. Attempting the manifest repair anyway so a restart can find the data; verify ${canonicalDir} exists if problems persist.`);
+                }
+                try {
+                  if (await this.saveManifest()) {
+                    logger.warn(`[store] Recovered: manifest now points at '${canonicalName}', matching the data's actual on-disk location${reopened ? "" : " (this process still has no working table handle \u2014 restart to serve it)"}.`);
+                  } else {
+                    logger.error(`[store] CRITICAL: could not persist a manifest matching disk after a failed rename revert. Data is intact on disk at ${canonicalDir} (table '${canonicalName}'), but the persisted manifest is stale and points at '${tempTableName}', which no longer exists. If this process exits before a future successful manifest save, the next start will not find the data automatically \u2014 manually repair the manifest to point at '${canonicalName}' before restarting.`);
+                  }
+                } catch (manifestErr) {
+                  logger.error(`[store] CRITICAL: manifest repair threw after a failed rename revert (${manifestErr}). Data is intact on disk at ${canonicalDir} (table '${canonicalName}'), but the persisted manifest is stale and points at '${tempTableName}'. Manually repair the manifest to point at '${canonicalName}' before restarting.`);
+                }
+              }
             }
           } catch (renameErr) {
             logger.warn(`[store] Directory rename failed, persisting temp table name in manifest: ${renameErr}`);
@@ -9292,6 +9335,15 @@ function resolveResearchModel(options) {
   }
   throw new Error(buildNoModelAvailableMessage());
 }
+function isPromptCachingActiveForModel(model) {
+  if (!model) return false;
+  if (model.api === "anthropic-messages") return true;
+  if (model.api === "openai-completions") {
+    const compat = model.compat;
+    return compat?.cacheControlFormat === "anthropic";
+  }
+  return false;
+}
 var init_research_model_resolver = __esm({
   "src/core/llm/research-model-resolver.ts"() {
     "use strict";
@@ -9429,6 +9481,7 @@ __export(research_knowledge_search_exports, {
   isTransientSynthesisError: () => isTransientSynthesisError,
   rebuildDocuments: () => rebuildDocuments,
   runBackgroundExtraction: () => runBackgroundExtraction,
+  splitPromptAtUserTurn: () => splitPromptAtUserTurn,
   triageRelevantUrls: () => triageRelevantUrls
 });
 import { Type as Type10 } from "typebox";
@@ -9572,13 +9625,28 @@ function isTransientSynthesisError(message) {
   // connection surfaces as `TypeError: terminated` (cause "other side closed" / UND_ERR_SOCKET).
   m.includes("terminated") || m.includes("other side closed") || m.includes("socket hang up") || m.includes("und_err");
 }
+function splitPromptAtUserTurn(template) {
+  const open5 = template.indexOf("<!-- USER_TURN");
+  if (open5 < 0) return { system: template, user: null };
+  const close = template.indexOf("-->", open5);
+  if (close < 0) return { system: template, user: null };
+  return {
+    system: template.slice(0, open5).trimEnd(),
+    user: template.slice(close + "-->".length).trimStart()
+  };
+}
 async function runBackgroundExtraction(model, auth, conversationHistory, queries, referenceDocuments, llmTimeout, maxTokens, thinkingLevel, signal, sessionId) {
   const promptTemplate = loadPrompt("research-knowledge-search-extractor");
   if (!promptTemplate) {
     throw new Error("research-knowledge-search prompt template not found");
   }
-  const systemPrompt = promptTemplate.replace("{{queries}}", () => formatQueriesBlock(queries)).replace("{{conversation_history}}", () => conversationHistory).replace("{{reference_documents}}", () => referenceDocuments);
-  const userMessage = "Analyze the reference documents above and extract the answer using the required JSON format.";
+  const { system, user } = splitPromptAtUserTurn(promptTemplate);
+  const fill = (t) => t.replace("{{queries}}", () => formatQueriesBlock(queries)).replace("{{conversation_history}}", () => conversationHistory).replace("{{reference_documents}}", () => referenceDocuments);
+  const finalInstruction = "Analyze the reference documents above and extract the answer using the required JSON format.";
+  const systemPrompt = user === null ? fill(system) : system;
+  const userMessage = user === null ? finalInstruction : `${fill(user)}
+
+${finalInstruction}`;
   let responseText;
   let attempt = 0;
   for (; ; ) {
@@ -9666,8 +9734,13 @@ async function triageRelevantUrls(model, auth, conversationHistory, queries, can
     return `[${i}] ${c.url}
 ${desc}`;
   }).join("\n\n");
-  const systemPrompt = promptTemplate.replace("{{queries}}", () => formatQueriesBlock(queries)).replace("{{conversation_history}}", () => conversationHistory).replace("{{candidates}}", () => candidateBlock);
-  const userMessage = "Return the JSON object listing the indices of the relevant candidates.";
+  const { system, user } = splitPromptAtUserTurn(promptTemplate);
+  const fill = (t) => t.replace("{{queries}}", () => formatQueriesBlock(queries)).replace("{{conversation_history}}", () => conversationHistory).replace("{{candidates}}", () => candidateBlock);
+  const finalInstruction = "Return the JSON object listing the indices of the relevant candidates.";
+  const systemPrompt = user === null ? fill(system) : system;
+  const userMessage = user === null ? finalInstruction : `${fill(user)}
+
+${finalInstruction}`;
   let responseText;
   let attempt = 0;
   for (; ; ) {
@@ -11250,7 +11323,12 @@ function isDegradableLlmError(error, signal) {
 function salvageReportText(raw) {
   const trimmed = raw.trim();
   if (trimmed.length <= 50) return "";
-  if (trimmed.startsWith("{") && /"(?:action|content|researchers)"\s*:/.test(trimmed)) {
+  let sniff = trimmed;
+  const fence = sniff.match(/^```[a-zA-Z0-9_-]*[ \t]*\r?\n/);
+  if (fence) {
+    sniff = sniff.slice(fence[0].length).replace(/\r?\n```\s*$/, "").trim();
+  }
+  if (sniff.startsWith("{") && /"(?:action|content|researchers)"\s*:/.test(sniff)) {
     return "";
   }
   return raw;
@@ -18621,7 +18699,7 @@ init_metrics();
 init_cancellation();
 function createScrapeTool(options) {
   const config = options.config || getConfig(options.ctx.cwd);
-  const maxScrapeBatches = getMaxScrapeBatches(config);
+  const maxScrapeBatches = options.tracker?.getToolLimit("scrape") ?? getMaxScrapeBatches(config);
   const container = tryGetServiceContainerFromCtx(options.ctx);
   const fallbackState = {
     version: 1,
@@ -22120,6 +22198,8 @@ var PermanentError = class extends Error {
 
 // src/youtube/index.ts
 init_metrics();
+init_text_utils();
+init_constants();
 function buildTranscriptDocument(r) {
   const header = [];
   if (r.title) header.push(`# ${r.title}`);
@@ -22197,7 +22277,7 @@ function formatResults(results, rejected) {
     md += `**Cite as:** ${r.url}${r.title ? ` \u2014 '${r.title}'${r.author ? ` by ${r.author}` : ""}` : ""}
 `;
     md += `
-${r.text}
+${truncateWithMarker(r.text ?? "", MAX_SCRAPE_CONTENT_CHARS_PER_DOC)}
 
 ---
 
@@ -22536,10 +22616,10 @@ var ToolUsageTracker = class {
     this.usage.clear();
   }
 };
-function createDefaultToolLimits(config) {
+function createDefaultToolLimits(config, cachingActive = false) {
   return {
     gathering: getMaxGatheringCalls(config),
-    scrape: getMaxScrapeBatches(config),
+    scrape: getMaxScrapeBatches(config, cachingActive),
     search: 1,
     youtube_transcript: 1,
     grep: MAX_GREP_CALLS,
@@ -22603,7 +22683,7 @@ async function createResearcherSession(options) {
   });
   logger.info(`[Researcher] Using model for researcher ${researcherId}: ${modelToUse.provider}/${modelToUse.id}`);
   try {
-    const tracker = new ToolUsageTracker(createDefaultToolLimits(config));
+    const tracker = new ToolUsageTracker(createDefaultToolLimits(config, isPromptCachingActiveForModel(modelToUse)));
     const globalLinks = updateGlobalLinks || (() => {
     });
     const customTools = createResearchTools({
@@ -22831,7 +22911,7 @@ function endResearchSession(piSessionId, researchId) {
     state.order.splice(index, 1);
     notifyOrderChange(sid);
   }
-  if (state.order.length === 0 && state.panels.size === 0) {
+  if (state.order.length === 0 && state.panels.size === 0 && state.aborts.size === 0) {
     state.steeringMessages = state.steeringMessages.filter((m) => m.status === "queued");
     const hasRemainingSteering = state.steeringMessages.length > 0;
     if (!hasRemainingSteering) {
@@ -22843,7 +22923,6 @@ function endResearchSession(piSessionId, researchId) {
     } else {
       state.failures.clear();
       state.failureReasons.clear();
-      state.aborts.clear();
     }
   }
 }
@@ -23007,6 +23086,7 @@ ${effectiveInitialLinks.map((l) => `- ${l}`).join("\n")}`;
   let lastError;
   const researcherExecutionStartMs = Date.now();
   const deliveredSteeringIds = /* @__PURE__ */ new Set();
+  const researcherSystemPrompt = injectCurrentDate(researcherPromptTemplate, "researcher").replace("{{extra_tool_guidelines}}", "").replace("{{digest_section}}", () => RESEARCHER_DIGEST_SECTION).trim();
   for (let attempt = 1; attempt <= maxAttempts; attempt++) {
     if (signal?.aborted) throw new Error("Aborted");
     if (stopRequested()) {
@@ -23040,14 +23120,25 @@ ${effectiveInitialLinks.map((l) => `- ${l}`).join("\n")}`;
     const allSteering = getSteeringMessages(sessionId);
     let steeringSection = "";
     if (allSteering.length > 0) {
-      steeringSection = "\n\n### ADDITIONAL USER GUIDANCE (Mandatory directional rules for your research)\n" + allSteering.map((m) => {
+      steeringSection = "### ADDITIONAL USER GUIDANCE (Mandatory directional rules for your research)\n" + allSteering.map((m) => {
         deliveredSteeringIds.add(m.id);
         return `- ${m.text}`;
       }).join("\n");
     }
-    const prompt = injectCurrentDate(researcherPromptTemplate, "researcher").replace("{{goal}}", () => researcherConfig.goal).replace("{{store_section}}", () => storeSection).replace("{{evidence_section}}", () => evidenceSection).replace("{{coordination_section}}", () => previousQueriesSection).replace("{{extra_tool_guidelines}}", "").replace("{{digest_section}}", () => RESEARCHER_DIGEST_SECTION).trim() + steeringSection;
+    const userMessage = [
+      `Topic: ${researcherConfig.name}
+Goal: ${researcherConfig.goal}`,
+      storeSection.trim(),
+      evidenceSection.trim(),
+      previousQueriesSection.trim(),
+      steeringSection,
+      "Perform your research and submit your full report now."
+    ].filter(Boolean).join("\n\n");
     logger.debug(`[ResearcherExecutor] Researcher ${id} attempt ${attempt} System Prompt:
-${prompt}`);
+${researcherSystemPrompt}
+
+User Message:
+${userMessage}`);
     const workerExclude = ["search"];
     const mergedExclude = [.../* @__PURE__ */ new Set([...workerExclude, ...options.excludeTools || []])];
     const scrapeEnabled = !mergedExclude.includes("scrape") && process.env["PI_RESEARCH_MOCK_SCRAPE"] !== "true";
@@ -23057,7 +23148,7 @@ ${prompt}`);
       cwd: ctx.cwd,
       ctxModel: model,
       modelRegistry: ctx.modelRegistry,
-      systemPrompt: prompt,
+      systemPrompt: researcherSystemPrompt,
       extensionCtx: ctx,
       excludeTools: mergedExclude,
       researcherId: id,
@@ -23172,10 +23263,7 @@ ${prompt}`);
       });
       let abortCleanup;
       try {
-        const promptPromise = session.prompt(`Topic: ${researcherConfig.name}
-Goal: ${researcherConfig.goal}
-
-Perform your research and submit your full report now.`);
+        const promptPromise = session.prompt(userMessage);
         promptPromise.catch((err) => logger.debug(`[ResearcherExecutor] Background session prompt rejection: ${err.message}`));
         await Promise.race([
           promptPromise,
@@ -23279,6 +23367,7 @@ init_logger();
 init_config();
 init_text_utils();
 init_constants();
+init_research_model_resolver();
 
 // src/orchestration/headless-observer.ts
 init_logger();
@@ -23474,7 +23563,10 @@ var QuickResearchOrchestrator = class {
         }
       }
       const researcherPromptTemplate = loadPrompt("researcher");
-      const maxScrapeBatches = getMaxScrapeBatches(this.config);
+      const cachingActiveForBudget = isPromptCachingActiveForModel(
+        resolveResearchModel({ modelRegistry: ctx.modelRegistry, config: this.config, hostModel: model, cwd: ctx.cwd })
+      );
+      const maxScrapeBatches = getMaxScrapeBatches(this.config, cachingActiveForBudget);
       const maxScrapeBatchesDisplay = maxScrapeBatches > 99 ? "unlimited" : maxScrapeBatches.toString();
       const quickEvidenceSection = `## Search
 You have access to the \`search\` tool. You get EXACTLY ONE search call \u2014 make it count.
@@ -23497,9 +23589,19 @@ Prioritize primary sources and authoritative data.`;
         evidenceLines.push("## Initial Links\nInvestigate these provided URLs first:\n" + this.options.initialLinks.map((l) => `- ${l}`).join("\n"));
       }
       evidenceLines.push(quickEvidenceSection);
-      const prompt = injectCurrentDate(researcherPromptTemplate, "researcher").replace("{{goal}}", () => query + steeringSection).replace("{{store_section}}", () => storeSection).replace("{{evidence_section}}", () => evidenceLines.join("\n\n")).replace("{{coordination_section}}", "").replace("{{extra_tool_guidelines}}", "- `search`: Perform broad web searches (Round 1 only).").replace("{{digest_section}}", "");
+      const prompt = injectCurrentDate(researcherPromptTemplate, "researcher").replace("{{extra_tool_guidelines}}", "- `search`: Perform broad web searches (Round 1 only).").replace("{{digest_section}}", "").trim();
+      const userMessage = [
+        `Goal: ${query}`,
+        storeSection.trim(),
+        evidenceLines.join("\n\n").trim(),
+        steeringSection.trim(),
+        "Perform your research and submit your full report now."
+      ].filter(Boolean).join("\n\n");
       logger.debug(`[QuickOrchestrator] System Prompt:
-${prompt}`);
+${prompt}
+
+User Message:
+${userMessage}`);
       let lastSeenSearchCount = 0;
       const { session, resolvedModel } = await createResearcherSession({
         cwd: ctx.cwd,
@@ -23593,7 +23695,7 @@ ${prompt}`);
         });
         let abortCleanup;
         try {
-          const promptPromise = session.prompt(query);
+          const promptPromise = session.prompt(userMessage);
           promptPromise.catch((err) => logger.debug(`[QuickOrchestrator] Background session prompt rejection: ${err.message}`));
           await Promise.race([
             promptPromise,
@@ -24743,6 +24845,10 @@ init_service_registry();
 init_service_names();
 var NO_SOURCES_NOTE = "CITED LINKS\n_No web sources were successfully retrieved for this report \u2014 searches or page fetches may have been blocked (for example by site bot-protection) or returned no usable results. Treat the findings above as unverified._";
 var UNVERIFIED_LINKS_NOTE = "_None of the links above could be verified: no page fetch succeeded this session and no citation could be matched to retrieved content. They may be inaccurate or invented \u2014 check each one before relying on it._";
+var WEAK_GROUNDING_MIN_SOURCES = 3;
+function weakGroundingNote(count) {
+  return `_Grounding notice: only ${count} source${count === 1 ? "" : "s"} could be verified for this report. Claims not attributable to the cited source` + (count === 1 ? "" : "s") + " above should be treated as unverified \u2014 cross-check anything load-bearing before relying on it._";
+}
 function redactUnverifiedProseUrls(text, trusted) {
   if (trusted.size === 0) return text;
   let removed = 0;
@@ -24985,6 +25091,14 @@ Research performed using ${modelId}`;
           body = rewriteCitationMarkers(body, localToGlobal, (n) => droppedNumbers.has(n));
         }
         body = redactUnverifiedProseUrls(body, trustedUrls);
+        if (globalCitations.length < WEAK_GROUNDING_MIN_SOURCES) {
+          logger.warn(`[ResearchSynthesisService] Report is weakly grounded: only ${globalCitations.length} verified source(s) \u2014 appending grounding notice.`);
+          return `${body}
+
+${weakGroundingNote(globalCitations.length)}
+
+${verifiedLinksSection}`;
+        }
         return `${body}
 
 ${verifiedLinksSection}`;
@@ -24993,6 +25107,14 @@ ${verifiedLinksSection}`;
       const validIds = new Set(globalCitations.map((c) => c.id));
       let prose = rewriteCitationMarkers(synthesis.trim(), /* @__PURE__ */ new Map(), (n) => !validIds.has(n));
       prose = redactUnverifiedProseUrls(prose, trustedUrls);
+      if (globalCitations.length < WEAK_GROUNDING_MIN_SOURCES) {
+        logger.warn(`[ResearchSynthesisService] Report is weakly grounded: only ${globalCitations.length} verified source(s) \u2014 appending grounding notice.`);
+        return `${prose}
+
+${weakGroundingNote(globalCitations.length)}
+
+${verifiedLinksSection}`;
+      }
       return `${prose}
 
 ${verifiedLinksSection}`;
@@ -25227,6 +25349,8 @@ function extractRunStats(snapshot) {
   };
   const errors = sumCounter(counters, "researcher_errors_total") + sumCounter(counters, "llm_api_errors_total");
   const tokens = sumCounter(counters, "llm_tokens_total");
+  const cacheReadTokens = sumCounter(counters, "llm_cache_read_tokens_total");
+  const cacheWriteTokens = sumCounter(counters, "llm_cache_write_tokens_total");
   const cost = sumCounter(counters, "llm_cost_total");
   let durationMs = 0;
   for (const key of Object.keys(histograms)) {
@@ -25261,6 +25385,8 @@ function extractRunStats(snapshot) {
     urlsFailed,
     errors,
     tokens,
+    cacheReadTokens,
+    cacheWriteTokens,
     cost,
     toolUsage
   };
@@ -25292,6 +25418,7 @@ var _onSignal = null;
 var _sigintHandler = null;
 var _sigtermHandler = null;
 var _sighupHandler = null;
+var _sigquitHandler = null;
 var _sigbreakHandler = null;
 var _shuttingDown = false;
 var _shutdownPromise = null;
@@ -25312,9 +25439,11 @@ function _registerSignalHandlers() {
   _sigintHandler = () => _onSignal?.("SIGINT");
   _sigtermHandler = () => _onSignal?.("SIGTERM");
   _sighupHandler = () => _onSignal?.("SIGHUP");
+  _sigquitHandler = () => _onSignal?.("SIGQUIT");
   process.on("SIGINT", _sigintHandler);
   process.on("SIGTERM", _sigtermHandler);
   process.on("SIGHUP", _sighupHandler);
+  process.on("SIGQUIT", _sigquitHandler);
   if (process.platform === "win32") {
     _sigbreakHandler = () => _onSignal?.("SIGBREAK");
     process.on("SIGBREAK", _sigbreakHandler);
@@ -25333,6 +25462,10 @@ function _removeSignalHandlers() {
     process.removeListener("SIGHUP", _sighupHandler);
     _sighupHandler = null;
   }
+  if (_sigquitHandler) {
+    process.removeListener("SIGQUIT", _sigquitHandler);
+    _sigquitHandler = null;
+  }
   if (_sigbreakHandler) {
     process.removeListener("SIGBREAK", _sigbreakHandler);
     _sigbreakHandler = null;
@@ -26019,10 +26152,17 @@ function makeProgressObserver() {
           }
           break;
         }
-        case "complete":
+        case "complete": {
           toStderr(`  \u2022 complete (${data?.result?.length ?? 0} chars)
 `);
+          const reportText = typeof data?.result === "string" ? data.result : "";
+          if (reportText.includes("No web sources were successfully retrieved") || reportText.includes("None of the links above could be verified")) {
+            toStderr("  \u2022 WARNING: no web sources could be retrieved \u2014 the report is unverified\n");
+          } else if (reportText.includes("Grounding notice: only")) {
+            toStderr("  \u2022 WARNING: weakly grounded report (fewer than 3 verified sources) \u2014 treat unattributed claims as unverified\n");
+          }
           break;
+        }
         case "error":
           toStderr(`  \u2022 error: ${data?.message}
 `);
@@ -26338,7 +26478,7 @@ Configure in:
       config: getConfig(process.cwd(), "cli"),
       ignoreGlobalConfig: true
     });
-    toStderr(`[pi-research] searching knowledge store (${queries.length} query/${queries.length === 1 ? "" : "s"})\u2026
+    toStderr(`[pi-research] searching knowledge store (${queries.length} ${queries.length === 1 ? "query" : "queries"})\u2026
 `);
     result = await searchKnowledge(queries, abortController.signal);
   } catch (err) {
@@ -26996,9 +27136,15 @@ async function main(argv) {
   process.on("SIGINT", () => onSignal("SIGINT"));
   process.on("SIGTERM", () => onSignal("SIGTERM"));
   process.on("SIGHUP", () => onSignal("SIGHUP"));
+  process.on("SIGQUIT", () => onSignal("SIGQUIT"));
   if (process.platform === "win32") {
     process.on("SIGBREAK", () => onSignal("SIGBREAK"));
   }
+  if (process.env["PI_RESEARCH_TEST_HANG_FOR_SIGNAL"] === "1") {
+    process.stdout.write("PI_RESEARCH_TEST_READY\n");
+    await new Promise(() => setInterval(() => {
+    }, 1e3));
+  }
   let parsed;
   try {
     parsed = parseArgs(argv);
@@ -27083,6 +27229,7 @@ export {
   cmdKnowledgeConfig,
   cmdResearch,
   exitCodeForSignal,
+  makeProgressObserver,
   parseArgs,
   reportError
 };

package/dist/prompts/research-knowledge-relevance-triage.md

@@ -18,6 +18,8 @@ Your ONLY job is to decide which candidates are genuinely relevant to the user's
 Field definitions:
 - `relevant_indices` (array of integers, required): the 0-based indices of the relevant candidates, in any order. Empty array `[]` if none are relevant.
 
+<!-- USER_TURN: everything below is delivered as the USER message of the stateless call, not the system prompt. The rules above stay byte-identical across calls so the provider can serve the system prefix from its prompt cache; the sections below vary per call. -->
+
 ## USER'S SEARCH QUERY
 
 Judge each candidate's relevance to this search query. This is the PRIMARY signal for what the user wants; the conversation below is supplementary and may be absent for a direct (non-conversational) search:

package/dist/prompts/research-knowledge-search-extractor.md

@@ -24,6 +24,8 @@ Field definitions:
 - `synthesis` (string, optional): The synthesized answer if found. Use inline citation markers [1], [2], etc. that correspond to the citations array. Present when answer_status is "yes" or "maybe". Omit when answer_status is "no".
 - `citations` (array of strings, required): The source URLs from the reference documents that were used to construct the answer. Empty array if answer_status is "no".
 
+<!-- USER_TURN: everything below is delivered as the USER message of the stateless call, not the system prompt. The rules above stay byte-identical across calls so the provider can serve the system prefix from its prompt cache; the sections below vary per call. -->
+
 ## USER'S SEARCH QUERY
 
 Answer this search query from the reference documents. This is the PRIMARY signal for what the user wants; the conversation below is supplementary and may be absent for a direct (non-conversational) search:

package/dist/prompts/researcher.md

@@ -2,7 +2,7 @@
 
 <!-- RESEARCHER_AGENT_MARKER -->
 
-You are an autonomous research agent. Your goal is to investigate your assigned topic with depth and rigor.
+You are an autonomous research agent. Your goal is to investigate your assigned topic with depth and rigor. Your specific goal, any historical knowledge-store results, your initial evidence/search results, and any sibling-coordination notes are provided in the user message that follows this system prompt — not here, so this system prompt stays byte-identical across every researcher and round (prompt caching).
 
 ## CORE DIRECTIVES (Strict Enforcement)
 
@@ -23,20 +23,10 @@ Do not treat any source as inherently objective. Justify its inclusion through t
 
 ---
 
-## Your Goal
-{{goal}}
-
-{{store_section}}
-(Note: when knowledge-store results appear above, they were retrieved automatically for your goal, aggregated from the **Project Knowledge Store** and **User Knowledge Store**. Do NOT try to search the store manually.)
-
-{{evidence_section}}
-
----
-
 ## Workflow
 
 ### Step 1: Build Your Source List
-Combine historical URLs and search results into a unified pool. Use previous session summaries as a guide for what to expect.
+Combine historical URLs and search results into a unified pool. Use previous session summaries as a guide for what to expect. Any knowledge-store results in your user message were retrieved automatically for your goal from the **Project Knowledge Store** and/or **User Knowledge Store** — cite them with that store name as their `Source:`.
 
 ### Step 2: Scrape Round 1
 Identify the 4 most promising URLs and scrape them in one batch (the scrape tool accepts up to 6 per call; 4 is your target per round). Prioritize primary sources, authoritative references, and dense documentation; all else being equal, lean toward more recent / current sources and topics.
@@ -51,8 +41,6 @@ Do NOT scrape URLs directly from the pool — only scrape URLs from your own sou
 ### Step 4: Synthesize
 Write your report immediately after scraping is complete, or as soon as a tool reports its limit is reached (e.g. "GATHERING LIMIT REACHED", "SEARCH LIMIT REACHED", "SCRAPE PROTOCOL COMPLETE"). Make no further tool calls after beginning synthesis.
 
-{{coordination_section}}
-
 ---
 
 ## Guidelines

package/dist/thread-worker.mjs

@@ -2332,7 +2332,7 @@ async function executeScrapeTask(_context, url, signal) {
         if (resp.request().resourceType() === "document" && resp.frame() === page.mainFrame()) {
           finalMainFrameAddr = resp.serverAddr().catch(() => null);
           const check2 = Promise.resolve(resp.headerValue("content-type")).then(async (ct) => {
-            const looksLikePdf = ct?.includes("application/pdf") || url.toLowerCase().endsWith(".pdf");
+            const looksLikePdf = ct?.includes("application/pdf") || String(resp.url()).toLowerCase().endsWith(".pdf");
             if (!looksLikePdf || oversizedPdfError || poisonedError) return;
             const declared = parseInt(await resp.headerValue("content-length").catch(() => null) || "", 10);
             if (Number.isFinite(declared) && declared > MAX_PDF_SIZE) {

package/docs/AGENT-SKILL.md

@@ -77,9 +77,10 @@ One-click (recommended). From the `pi` extension, run `/research-config` →
 Install in External Agents. The installer:
 
 1. Detects which target agents are present under `$HOME` — currently Claude
-   (`~/.claude/skills`), OpenAI Codex CLI (`~/.codex/skills`), and OpenClaw
-   (`~/.openclaw/skills`, OpenClaw's managed skill root, which accepts symlinked
-   skill folders).
+   (`~/.claude/skills`), OpenClaw (`~/.openclaw/skills`, OpenClaw's managed
+   skill root, which accepts symlinked skill folders), and OpenAI Codex CLI
+   (`~/.codex/skills` — unlike the other two, this path is not confirmed by
+   Codex's official docs; Codex skills support is still emerging).
 2. Symlinks `skills/pi-research/` into each present agent, never overwriting an
    unrelated skill already in that slot.
 3. Records what it created in a manifest, so Remove from External Agents