@lincoln504/pi-research 1.4.1 → 1.5.0

package/dist/cli.mjs

@@ -241,6 +241,8 @@ function redactSecrets(message) {
   }
   if (out.length > MAX_LOG_MESSAGE_LENGTH) {
     out = `${out.slice(0, keep)}\u2026[truncated ${Math.max(rawLength, out.length) - keep} chars]`;
+  } else if (rawLength > scanEnd) {
+    out = `${out}\u2026[truncated ${rawLength - scanEnd} chars]`;
   }
   return out;
 }
@@ -2279,7 +2281,9 @@ import { createRequire as createRequire2 } from "node:module";
 function getConfigDirName() {
   if (_configDirName !== void 0) return _configDirName;
   const override = process.env["PI_RESEARCH_CONFIG_DIR_NAME"];
-  if (override) return _configDirName = override;
+  if (override && !override.includes("/") && !override.includes("\\") && override !== "." && override !== "..") {
+    return _configDirName = override;
+  }
   try {
     const require2 = createRequire2(import.meta.url);
     const host = require2("@earendil-works/pi-coding-agent");
@@ -2639,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))
       );
@@ -2672,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;
@@ -2961,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";
@@ -3031,10 +3038,16 @@ var init_config = __esm({
       SEARCH_TIMEOUT_MS: Type.Number({ minimum: 5e3, maximum: 12e4, default: 45e3 }),
       /** TUI refresh debounce in milliseconds (default: 100ms) */
       TUI_REFRESH_DEBOUNCE_MS: Type.Number({ minimum: 0, maximum: 1e3, default: 100 }),
-      /** Queue-wait / overhead margin (ms) added on top of each browser operation's own nav
-       *  timeout to form its scheduler task-timeout ceiling: a search task times out after
-       *  SEARCH_TIMEOUT_MS + this, a scrape after SCRAPE_TIMEOUT_MS + this. Sized so a task is
-       *  never killed before it has used its full nav budget plus time waiting in the queue.
+      /** Overhead margin (ms) added on top of each browser operation's own nav timeout to
+       *  form its scheduler task-timeout ceiling: a search task times out after
+       *  SEARCH_TIMEOUT_MS + this, a scrape after SCRAPE_TIMEOUT_MS + this — covering
+       *  per-task work beyond raw navigation (page setup, result parsing). Queue wait is
+       *  NOT part of this margin: the deadline is armed on dispatch, not on enqueue, so
+       *  time spent waiting for a free worker never counts against it (see
+       *  browser-task-scheduler.ts). Cold browser-launch/context-creation time is also
+       *  separate from this margin — COLD_START_ALLOWANCE_MS
+       *  (infrastructure/browser/config.ts) covers that unconditionally on top of it,
+       *  since it isn't something a user should need to tune.
        *  (default: 10000) */
       BROWSER_TASK_TIMEOUT_MS: Type.Number({ minimum: 2e3, maximum: 12e4, default: 1e4 }),
       /** Timeout for coordinator/research-lead/repair/knowledge LLM calls in ms (default: 300000 = 5 min, range: 60s-30min).
@@ -3174,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();
   }
 });
@@ -3186,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;
   }
@@ -4330,12 +4345,12 @@ async function isModelCached(model) {
     const cacheDir = env.cacheDir;
     if (!cacheDir) return false;
     const { access: access3, readdir: readdir6, readFile: readFile7, stat: stat6, rm: rm3 } = await import("node:fs/promises");
-    const path19 = await import("node:path");
-    const modelDir = path19.default.join(cacheDir, model);
-    const onnxDir = path19.default.join(modelDir, "onnx");
-    await access3(path19.default.join(onnxDir, "model.onnx"));
+    const path20 = await import("node:path");
+    const modelDir = path20.default.join(cacheDir, model);
+    const onnxDir = path20.default.join(modelDir, "onnx");
+    await access3(path20.default.join(onnxDir, "model.onnx"));
     try {
-      const cfgRaw = await readFile7(path19.default.join(modelDir, "config.json"), "utf-8");
+      const cfgRaw = await readFile7(path20.default.join(modelDir, "config.json"), "utf-8");
       JSON.parse(cfgRaw);
     } catch {
       return false;
@@ -4343,7 +4358,7 @@ async function isModelCached(model) {
     const tokenizerFiles = ["tokenizer.json", "tokenizer.model", "vocab.txt"];
     let hasTokenizer = false;
     for (const f of tokenizerFiles) {
-      const st = await stat6(path19.default.join(modelDir, f)).catch(() => null);
+      const st = await stat6(path20.default.join(modelDir, f)).catch(() => null);
       if (st && st.size > 0) {
         hasTokenizer = true;
         break;
@@ -4353,7 +4368,7 @@ async function isModelCached(model) {
     const entries = await readdir6(onnxDir).catch(() => []);
     const hasExternalWeights = entries.includes("model.onnx_data");
     if (hasExternalWeights) {
-      const dataStat = await stat6(path19.default.join(onnxDir, "model.onnx_data")).catch(() => null);
+      const dataStat = await stat6(path20.default.join(onnxDir, "model.onnx_data")).catch(() => null);
       if (!dataStat || dataStat.size === 0) return false;
     }
     const partialArtifacts = entries.filter(
@@ -4362,7 +4377,7 @@ async function isModelCached(model) {
     if (partialArtifacts.length > 0) {
       if (hasExternalWeights) {
         for (const f of partialArtifacts) {
-          await rm3(path19.default.join(onnxDir, f), { force: true }).catch(() => {
+          await rm3(path20.default.join(onnxDir, f), { force: true }).catch(() => {
           });
         }
       } else {
@@ -4384,10 +4399,10 @@ async function purgeModelCache(model) {
     const cacheDir = env.cacheDir;
     if (!cacheDir) return;
     const { rm: rm3 } = await import("node:fs/promises");
-    const path19 = await import("node:path");
-    const resolvedCache = path19.default.resolve(cacheDir);
-    const modelDir = path19.default.resolve(resolvedCache, model);
-    if (!model || path19.default.isAbsolute(model) || modelDir === resolvedCache || !modelDir.startsWith(resolvedCache + path19.default.sep)) {
+    const path20 = await import("node:path");
+    const resolvedCache = path20.default.resolve(cacheDir);
+    const modelDir = path20.default.resolve(resolvedCache, model);
+    if (!model || path20.default.isAbsolute(model) || modelDir === resolvedCache || !modelDir.startsWith(resolvedCache + path20.default.sep)) {
       logger.warn(`[embedder] Refusing to purge unsafe model-cache path for model id ${JSON.stringify(model)}`);
       return;
     }
@@ -4470,7 +4485,7 @@ async function handleWebGPULoadError(loadErr, pipeline, stateManager, gpuLockHel
     return { success: false, error };
   }
 }
-async function handleWebGPUWarmupError(warmupErr, pipeline, stateManager, gpuLockHeld, model, initializationTimeoutMs, useCache) {
+async function handleWebGPUWarmupError(warmupErr, pipeline, stateManager, gpuLockHeld, model, initializationTimeoutMs, useCache, poolingMode = "mean") {
   markWebGpuFallback();
   logger.warn(
     "[embedder] WebGPU error during warmup \u2014 falling back to CPU. The underlying cause (commonly VRAM exhaustion) is in the native Dawn/ONNX output logged just above this line."
@@ -4487,7 +4502,7 @@ async function handleWebGPUWarmupError(warmupErr, pipeline, stateManager, gpuLoc
   try {
     const cpuPipeline = await loadModelOnCPU(model, initializationTimeoutMs, useCache);
     logger.info("[embedder] CPU pipeline loaded successfully");
-    const { dummy, success, error: cpuWarmupErr } = await warmupPipeline(cpuPipeline, "mean", useCache);
+    const { dummy, success, error: cpuWarmupErr } = await warmupPipeline(cpuPipeline, poolingMode, useCache);
     if (!success || cpuWarmupErr) {
       logger.error("[embedder] CPU fallback pipeline warmup failed:", cpuWarmupErr);
       if (cpuPipeline) {
@@ -4906,7 +4921,8 @@ var init_embedder = __esm({
                 this.gpuLockHeld,
                 this.model,
                 this.initializationTimeoutMs,
-                this.useCache
+                this.useCache,
+                this.poolingMode
               );
               if (!result.success) {
                 throw result.error;
@@ -4968,9 +4984,12 @@ var init_embedder = __esm({
       truncateText(text) {
         const maxChars = this.maxTokens * this.charsPerToken;
         if (text.length > maxChars) {
+          let keep = maxChars;
+          const lastKeptUnit = text.charCodeAt(keep - 1);
+          if (lastKeptUnit >= 55296 && lastKeptUnit <= 56319) keep -= 1;
           metrics.increment("embedder_truncations_total", 1, { model: this.model });
-          logger.debug(`[embedder] Truncated input for embedding: ${text.length} -> ${maxChars} chars (model=${this.model})`);
-          return text.slice(0, maxChars);
+          logger.debug(`[embedder] Truncated input for embedding: ${text.length} -> ${keep} chars (model=${this.model})`);
+          return text.slice(0, keep);
         }
         return text;
       }
@@ -5432,6 +5451,11 @@ var init_embedding_server = __esm({
       hardDeadlineMs;
       onPoison;
       poisoned = null;
+      // The currently-executing task's real work promise (not the soft-timeout race) —
+      // set only while a native call is actually in flight. Lets a caller that needs
+      // to dispose the underlying pipeline (EmbeddingServer.shutdown) wait for true
+      // idleness instead of racing disposal against a still-running inference.
+      currentWork = null;
       constructor(maxDepth = 200, timeoutMs = 12e4, hardDeadlineMs = 6e5, onPoison) {
         this.maxDepth = maxDepth;
         this.timeoutMs = timeoutMs;
@@ -5457,6 +5481,7 @@ var init_embedding_server = __esm({
             let hardTimer;
             try {
               work = fn();
+              this.currentWork = work;
               hardTimer = setTimeout(() => {
                 if (settled) return;
                 this.poison(new Error(
@@ -5477,6 +5502,7 @@ var init_embedding_server = __esm({
               } finally {
                 settled = true;
                 if (hardTimer !== void 0) clearTimeout(hardTimer);
+                if (this.currentWork === work) this.currentWork = null;
               }
             }
           };
@@ -5484,6 +5510,40 @@ var init_embedding_server = __esm({
           if (!this.running) void this.pump();
         });
       }
+      /**
+       * 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 || this.running) {
+          if (this.currentWork) {
+            await this.currentWork.catch(() => {
+            });
+          } else {
+            await Promise.resolve();
+          }
+        }
+      }
       poison(err) {
         if (this.poisoned) return;
         this.poisoned = err;
@@ -5665,6 +5725,7 @@ var init_embedding_server = __esm({
           this.server = null;
         }
         if (disposeEmbedder) {
+          await this.queue.waitForIdle();
           await this.embedder.dispose().catch((err) => {
             if (this.isShuttingDown) {
               logger.debug("[EmbeddingServer] Error disposing embedder during shutdown (expected):", err);
@@ -5895,7 +5956,7 @@ var init_embedding_client = __esm({
         }
       }
       // ---- Internal HTTP helpers ----
-      getRequest(path19, timeoutMs = 12e4) {
+      getRequest(path20, timeoutMs = 12e4) {
         return new Promise((resolve9, reject) => {
           let resolved = false;
           let req;
@@ -5903,7 +5964,7 @@ var init_embedding_client = __esm({
             if (!resolved) {
               resolved = true;
               req?.destroy();
-              reject(new Error(`[EmbeddingClient] GET ${path19} timed out after ${timeoutMs}ms`));
+              reject(new Error(`[EmbeddingClient] GET ${path20} timed out after ${timeoutMs}ms`));
             }
           }, timeoutMs);
           if (timer.unref) timer.unref();
@@ -5911,7 +5972,7 @@ var init_embedding_client = __esm({
             {
               hostname: "127.0.0.1",
               port: this.port,
-              path: path19,
+              path: path20,
               method: "GET",
               headers: this.authHeaders()
             },
@@ -5927,19 +5988,19 @@ var init_embedding_client = __esm({
                 try {
                   const parsed = JSON.parse(collected.toString());
                   if (res.statusCode !== 200) {
-                    reject(new Error(`[EmbeddingClient] GET ${path19} returned HTTP ${res.statusCode}`));
+                    reject(new Error(`[EmbeddingClient] GET ${path20} returned HTTP ${res.statusCode}`));
                   } else {
                     resolve9(parsed);
                   }
                 } catch (_e) {
-                  reject(new Error(`[EmbeddingClient] Failed to parse GET ${path19} response: ${collected.toString()}`));
+                  reject(new Error(`[EmbeddingClient] Failed to parse GET ${path20} response: ${collected.toString()}`));
                 }
               });
               res.on("error", (err) => {
                 if (resolved) return;
                 resolved = true;
                 clearTimeout(timer);
-                reject(new Error(`[EmbeddingClient] GET ${path19} response error: ${err.message}`));
+                reject(new Error(`[EmbeddingClient] GET ${path20} response error: ${err.message}`));
               });
             }
           );
@@ -5947,12 +6008,12 @@ var init_embedding_client = __esm({
             if (resolved) return;
             resolved = true;
             clearTimeout(timer);
-            reject(new Error(`[EmbeddingClient] GET ${path19} request error: ${err.message}`));
+            reject(new Error(`[EmbeddingClient] GET ${path20} request error: ${err.message}`));
           });
           req.end();
         });
       }
-      request(path19, data) {
+      request(path20, data) {
         return new Promise((resolve9, reject) => {
           const timeoutMs = 12e4;
           let resolved = false;
@@ -5961,7 +6022,7 @@ var init_embedding_client = __esm({
             if (!resolved) {
               resolved = true;
               req?.destroy();
-              reject(new Error(`[EmbeddingClient] POST ${path19} timed out after ${timeoutMs}ms`));
+              reject(new Error(`[EmbeddingClient] POST ${path20} timed out after ${timeoutMs}ms`));
             }
           }, timeoutMs);
           if (timer.unref) timer.unref();
@@ -5970,7 +6031,7 @@ var init_embedding_client = __esm({
             {
               hostname: "127.0.0.1",
               port: this.port,
-              path: path19,
+              path: path20,
               method: "POST",
               headers: {
                 "Content-Type": "application/json",
@@ -5996,14 +6057,14 @@ var init_embedding_client = __esm({
                     resolve9(parsed);
                   }
                 } catch (_e) {
-                  reject(new Error(`[EmbeddingClient] Failed to parse POST ${path19} response: ${collected.toString()}`));
+                  reject(new Error(`[EmbeddingClient] Failed to parse POST ${path20} response: ${collected.toString()}`));
                 }
               });
               res.on("error", (err) => {
                 if (resolved) return;
                 resolved = true;
                 clearTimeout(timer);
-                reject(new Error(`[EmbeddingClient] POST ${path19} response error: ${err.message}`));
+                reject(new Error(`[EmbeddingClient] POST ${path20} response error: ${err.message}`));
               });
             }
           );
@@ -6011,7 +6072,7 @@ var init_embedding_client = __esm({
             if (resolved) return;
             resolved = true;
             clearTimeout(timer);
-            reject(new Error(`[EmbeddingClient] POST ${path19} request error: ${err.message}`));
+            reject(new Error(`[EmbeddingClient] POST ${path20} request error: ${err.message}`));
           });
           req.write(body);
           req.end();
@@ -7640,8 +7701,36 @@ var init_store = __esm({
             const canonicalDir = path15.join(this.options.dbDir, `${canonicalName}.lance`);
             await fsPromises.rename(tempDir, canonicalDir);
             this.tableName = canonicalName;
-            await this.saveManifest();
-            this.table = await this.db.openTable(this.tableName);
+            if (await this.saveManifest()) {
+              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.");
+              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}`);
             this.tableName = tempTableName;
@@ -8693,6 +8782,7 @@ var init_chunker = __esm({
 
 // src/knowledge/index.ts
 import * as fs14 from "node:fs";
+import * as path16 from "node:path";
 function getMigrationStrategy(config) {
   const strategy = config.MIGRATION_STRATEGY;
   if (!strategy) return void 0;
@@ -8754,15 +8844,25 @@ async function createKnowledgeStoreComponents(embedderFactory, reconnectFactory,
 }
 async function forceDeleteKnowledgeStore(config, workspace) {
   const dbDir = getDbDir(config, workspace);
-  if (fs14.existsSync(dbDir)) {
-    try {
-      fs14.rmSync(dbDir, { recursive: true, force: true, maxRetries: 5, retryDelay: 50 });
-      fs14.mkdirSync(dbDir, { recursive: true });
-      logger.info(`[knowledge] Knowledge store at ${dbDir} forcefully deleted and recreated.`);
-    } catch (err) {
-      logger.error(`[knowledge] Failed to forcefully delete directory ${dbDir}:`, err);
-      throw err;
+  if (!fs14.existsSync(dbDir)) return;
+  let tableName = "knowledge";
+  const manifestPath = path16.join(dbDir, "store-manifest.json");
+  try {
+    if (fs14.existsSync(manifestPath)) {
+      const manifest = JSON.parse(fs14.readFileSync(manifestPath, "utf-8"));
+      if (manifest.activeTableName) tableName = manifest.activeTableName;
     }
+  } catch (err) {
+    logger.warn(`[knowledge] Failed to read manifest before forced delete, defaulting to table '${tableName}':`, err);
+  }
+  const tableDir = path16.join(dbDir, `${tableName}.lance`);
+  if (!fs14.existsSync(tableDir)) return;
+  try {
+    fs14.rmSync(tableDir, { recursive: true, force: true, maxRetries: 5, retryDelay: 50 });
+    logger.info(`[knowledge] Corrupted table directory ${tableDir} forcefully deleted; will be recreated on next init.`);
+  } catch (err) {
+    logger.error(`[knowledge] Failed to forcefully delete table directory ${tableDir}:`, err);
+    throw err;
   }
 }
 var MAX_INIT_RETRIES, BASE_RETRY_DELAY_MS, MAX_RETRY_DELAY_MS;
@@ -8787,7 +8887,7 @@ var knowledge_store_service_exports = {};
 __export(knowledge_store_service_exports, {
   KnowledgeStoreService: () => KnowledgeStoreService
 });
-import * as path16 from "node:path";
+import * as path17 from "node:path";
 var KnowledgeStoreService;
 var init_knowledge_store_service = __esm({
   "src/infrastructure/knowledge-store-service.ts"() {
@@ -8881,7 +8981,7 @@ var init_knowledge_store_service = __esm({
             };
             const container = tryGetServiceContainerFromCtx(ctx);
             const pathConfig = await getService(ServiceNames.STATE_PATH_CONFIGURATION, void 0, container);
-            const lockPath = path16.join(pathConfig.getLockDirPath(), "knowledge-store-init.lock");
+            const lockPath = path17.join(pathConfig.getLockDirPath(), "knowledge-store-init.lock");
             if (!this._initLock) {
               const processLifecycle = await getService(ServiceNames.PROCESS_LIFECYCLE, void 0, container);
               this._initLock = new FileLockService({
@@ -9235,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";
@@ -9372,6 +9481,7 @@ __export(research_knowledge_search_exports, {
   isTransientSynthesisError: () => isTransientSynthesisError,
   rebuildDocuments: () => rebuildDocuments,
   runBackgroundExtraction: () => runBackgroundExtraction,
+  splitPromptAtUserTurn: () => splitPromptAtUserTurn,
   triageRelevantUrls: () => triageRelevantUrls
 });
 import { Type as Type10 } from "typebox";
@@ -9515,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 (; ; ) {
@@ -9609,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 (; ; ) {
@@ -9942,11 +10072,11 @@ __export(skill_installer_exports, {
 import * as crypto10 from "node:crypto";
 import * as fs16 from "node:fs";
 import * as os6 from "node:os";
-import * as path17 from "node:path";
+import * as path18 from "node:path";
 import { fileURLToPath as fileURLToPath4 } from "node:url";
 function readSkillVersion(sourceDir) {
   try {
-    const md = fs16.readFileSync(path17.join(sourceDir, "SKILL.md"), "utf-8");
+    const md = fs16.readFileSync(path18.join(sourceDir, "SKILL.md"), "utf-8");
     return /"version"\s*:\s*"([^"]+)"/.exec(md)?.[1] ?? null;
   } catch {
     return null;
@@ -9961,7 +10091,7 @@ function resolveSkillSourceDir(explicit) {
   if (process.env["PI_RESEARCH_SKILL_DIR"]) candidates.push(process.env["PI_RESEARCH_SKILL_DIR"]);
   const fromHere = (() => {
     try {
-      return path17.dirname(fileURLToPath4(import.meta.url));
+      return path18.dirname(fileURLToPath4(import.meta.url));
     } catch {
       return void 0;
     }
@@ -9970,22 +10100,22 @@ function resolveSkillSourceDir(explicit) {
     if (!start) continue;
     let dir = start;
     for (let i = 0; i < 8; i++) {
-      candidates.push(path17.join(dir, "skills", SKILL_NAME));
-      const parent = path17.dirname(dir);
+      candidates.push(path18.join(dir, "skills", SKILL_NAME));
+      const parent = path18.dirname(dir);
       if (parent === dir) break;
       dir = parent;
     }
   }
   for (const c of candidates) {
     try {
-      if (fs16.existsSync(path17.join(c, "SKILL.md"))) return path17.resolve(c);
+      if (fs16.existsSync(path18.join(c, "SKILL.md"))) return path18.resolve(c);
     } catch {
     }
   }
   throw new Error("Could not locate the bundled research skill (skills/pi-research/SKILL.md). Set PI_RESEARCH_SKILL_DIR to its path.");
 }
 function getManifestPath(opts) {
-  return path17.join(homeDir(opts), ".pi", "research", "installed-skills.json");
+  return path18.join(homeDir(opts), ".pi", "research", "installed-skills.json");
 }
 function readManifest(opts) {
   const p = getManifestPath(opts);
@@ -10002,7 +10132,7 @@ function readManifest(opts) {
 }
 function writeManifest(manifest, opts) {
   const p = getManifestPath(opts);
-  fs16.mkdirSync(path17.dirname(p), { recursive: true });
+  fs16.mkdirSync(path18.dirname(p), { recursive: true });
   const tmp = `${p}.tmp.${process.pid}.${Date.now()}.${manifestTmpSeq++}`;
   fs16.writeFileSync(tmp, JSON.stringify(manifest, null, 2) + "\n", "utf-8");
   try {
@@ -10024,8 +10154,8 @@ function isOwnedSymlink(targetPath, expectedSource) {
   try {
     const st = fs16.lstatSync(targetPath);
     if (!st.isSymbolicLink()) return false;
-    const dest = path17.resolve(path17.dirname(targetPath), fs16.readlinkSync(targetPath));
-    if (expectedSource && path17.resolve(expectedSource) === dest) return true;
+    const dest = path18.resolve(path18.dirname(targetPath), fs16.readlinkSync(targetPath));
+    if (expectedSource && path18.resolve(expectedSource) === dest) return true;
     return /[/\\]pi-research[/\\]skills[/\\]pi-research$/.test(dest);
   } catch {
     return false;
@@ -10033,7 +10163,7 @@ function isOwnedSymlink(targetPath, expectedSource) {
 }
 function isOwnedCopy(targetPath) {
   try {
-    const md = fs16.readFileSync(path17.join(targetPath, "SKILL.md"), "utf-8");
+    const md = fs16.readFileSync(path18.join(targetPath, "SKILL.md"), "utf-8");
     return md.includes(PACKAGE_NAME);
   } catch {
     return false;
@@ -10042,11 +10172,11 @@ function isOwnedCopy(targetPath) {
 function detectHarnesses(opts) {
   const home = homeDir(opts);
   return HARNESSES.map((h) => {
-    const absSkillsDir = path17.join(home, h.skillsDir);
-    const absSkillPath = path17.join(absSkillsDir, SKILL_NAME);
+    const absSkillsDir = path18.join(home, h.skillsDir);
+    const absSkillPath = path18.join(absSkillsDir, SKILL_NAME);
     let present = false;
     try {
-      present = fs16.existsSync(path17.join(home, h.baseDir));
+      present = fs16.existsSync(path18.join(home, h.baseDir));
     } catch {
     }
     let installed = "none";
@@ -10087,15 +10217,15 @@ function installSkill(toolIds, opts = {}) {
       results.push({ tool: id, path: "", type: "symlink", status: "error", message: `unknown target "${id}"` });
       continue;
     }
-    const absSkillsDir = path17.join(home, def.skillsDir);
-    const absSkillPath = path17.join(absSkillsDir, SKILL_NAME);
+    const absSkillsDir = path18.join(home, def.skillsDir);
+    const absSkillPath = path18.join(absSkillsDir, SKILL_NAME);
     const type = opts.copy ? "copy" : "symlink";
     if (isOwnedSymlink(absSkillPath, source) || isOwnedCopy(absSkillPath)) {
       try {
         const lst = fs16.lstatSync(absSkillPath);
         if (lst.isSymbolicLink()) {
-          const dest = path17.resolve(path17.dirname(absSkillPath), fs16.readlinkSync(absSkillPath));
-          if (dest !== path17.resolve(source)) {
+          const dest = path18.resolve(path18.dirname(absSkillPath), fs16.readlinkSync(absSkillPath));
+          if (dest !== path18.resolve(source)) {
             if (opts.dryRun) {
               results.push({ tool: id, path: absSkillPath, type: "symlink", status: "planned", message: "would re-point stale symlink to current source" });
               continue;
@@ -10171,7 +10301,7 @@ function uninstallSkill(toolIds, opts = {}) {
     }
   }
   for (const { tool, path: skillPath } of targets.values()) {
-    if (toolIds && toolIds.length && !toolIds.includes(tool)) {
+    if (toolIds !== void 0 && !toolIds.includes(tool)) {
       const e = manifest.entries.find((x) => x.path === skillPath);
       if (e) keep.push(e);
       continue;
@@ -10232,19 +10362,19 @@ function reconcileSkillInstalls(opts = {}) {
     if (e.type !== "symlink") {
       const stale2 = currentVersion !== null && e.version !== currentVersion;
       if (stale2 && source !== null && fs16.existsSync(e.path) && isOwnedCopy(e.path)) {
-        const dir2 = path17.dirname(e.path);
-        const base2 = path17.basename(e.path);
+        const dir2 = path18.dirname(e.path);
+        const base2 = path18.basename(e.path);
         try {
           for (const name of fs16.readdirSync(dir2)) {
             if (name.startsWith(`.${base2}.new-`) || name.startsWith(`.${base2}.old-`)) {
-              fs16.rmSync(path17.join(dir2, name), { recursive: true, force: true });
+              fs16.rmSync(path18.join(dir2, name), { recursive: true, force: true });
             }
           }
         } catch {
         }
         const suffix = crypto10.randomBytes(4).toString("hex");
-        const fresh = path17.join(dir2, `.${base2}.new-${suffix}`);
-        const retired = path17.join(dir2, `.${base2}.old-${suffix}`);
+        const fresh = path18.join(dir2, `.${base2}.new-${suffix}`);
+        const retired = path18.join(dir2, `.${base2}.old-${suffix}`);
         try {
           copyDir(source, fresh);
         } catch {
@@ -10290,12 +10420,12 @@ function reconcileSkillInstalls(opts = {}) {
       }
       continue;
     }
-    const dir = path17.dirname(e.path);
-    const base = path17.basename(e.path);
+    const dir = path18.dirname(e.path);
+    const base = path18.basename(e.path);
     try {
       for (const name of fs16.readdirSync(dir)) {
         if (name.startsWith(`.${base}.new-`)) {
-          fs16.rmSync(path17.join(dir, name), { recursive: true, force: true });
+          fs16.rmSync(path18.join(dir, name), { recursive: true, force: true });
         }
       }
     } catch {
@@ -10311,10 +10441,10 @@ function reconcileSkillInstalls(opts = {}) {
     const targetLive = fs16.existsSync(e.path);
     let dest = null;
     try {
-      dest = path17.resolve(path17.dirname(e.path), fs16.readlinkSync(e.path));
+      dest = path18.resolve(path18.dirname(e.path), fs16.readlinkSync(e.path));
     } catch {
     }
-    const stale = source !== null && dest !== null && dest !== path17.resolve(source);
+    const stale = source !== null && dest !== null && dest !== path18.resolve(source);
     if (!targetLive || stale) {
       if (source !== null) {
         try {
@@ -10329,7 +10459,7 @@ function reconcileSkillInstalls(opts = {}) {
           result.repointed.push(e.path);
         } catch {
           const suffix = crypto10.randomBytes(4).toString("hex");
-          const fresh = path17.join(dir, `.${base}.new-${suffix}`);
+          const fresh = path18.join(dir, `.${base}.new-${suffix}`);
           try {
             copyDir(source, fresh);
             fs16.renameSync(fresh, e.path);
@@ -10371,7 +10501,7 @@ function copyDir(src, dest) {
   if (st.isDirectory()) {
     fs16.mkdirSync(dest, { recursive: true });
     for (const name of fs16.readdirSync(src)) {
-      copyDir(path17.join(src, name), path17.join(dest, name));
+      copyDir(path18.join(src, name), path18.join(dest, name));
     }
   } else {
     fs16.copyFileSync(src, dest);
@@ -10382,12 +10512,12 @@ var init_skill_installer = __esm({
   "src/skill-install/skill-installer.ts"() {
     "use strict";
     HARNESSES = [
-      { id: "claude", label: "Claude", baseDir: ".claude", skillsDir: path17.join(".claude", "skills"), confidence: "confirmed" },
-      { id: "openclaw", label: "OpenClaw", baseDir: ".openclaw", skillsDir: path17.join(".openclaw", "skills"), confidence: "confirmed", note: "OpenClaw reads ~/.openclaw/skills as a managed skill root and accepts symlinked skill folders (docs.openclaw.ai/tools/skills)." },
-      { id: "pi", label: "pi", baseDir: ".pi", skillsDir: path17.join(".pi", "skills"), confidence: "confirmed" },
-      { id: "cursor", label: "Cursor", baseDir: ".cursor", skillsDir: path17.join(".cursor", "skills"), confidence: "partial", note: "Cursor project-level skills are documented; the global ~/.cursor/skills path is community-reported." },
-      { id: "codex", label: "OpenAI Codex CLI", baseDir: ".codex", skillsDir: path17.join(".codex", "skills"), confidence: "unverified", note: "Codex skills support is emerging; path not confirmed by official docs." },
-      { id: "agents", label: "Cross-tool (~/.agents/skills)", baseDir: ".agents", skillsDir: path17.join(".agents", "skills"), confidence: "unverified", note: "Proposed Universal Agents convention; not yet a ratified standard." }
+      { id: "claude", label: "Claude", baseDir: ".claude", skillsDir: path18.join(".claude", "skills"), confidence: "confirmed" },
+      { id: "openclaw", label: "OpenClaw", baseDir: ".openclaw", skillsDir: path18.join(".openclaw", "skills"), confidence: "confirmed", note: "OpenClaw reads ~/.openclaw/skills as a managed skill root and accepts symlinked skill folders (docs.openclaw.ai/tools/skills)." },
+      { id: "pi", label: "pi", baseDir: ".pi", skillsDir: path18.join(".pi", "skills"), confidence: "confirmed" },
+      { id: "cursor", label: "Cursor", baseDir: ".cursor", skillsDir: path18.join(".cursor", "skills"), confidence: "partial", note: "Cursor project-level skills are documented; the global ~/.cursor/skills path is community-reported." },
+      { id: "codex", label: "OpenAI Codex CLI", baseDir: ".codex", skillsDir: path18.join(".codex", "skills"), confidence: "unverified", note: "Codex skills support is emerging; path not confirmed by official docs." },
+      { id: "agents", label: "Cross-tool (~/.agents/skills)", baseDir: ".agents", skillsDir: path18.join(".agents", "skills"), confidence: "unverified", note: "Proposed Universal Agents convention; not yet a ratified standard." }
     ];
     SKILL_NAME = "pi-research";
     PACKAGE_NAME = "@lincoln504/pi-research";
@@ -10400,7 +10530,7 @@ var init_skill_installer = __esm({
 // src/cli.ts
 import * as fs17 from "node:fs";
 import * as os7 from "node:os";
-import * as path18 from "node:path";
+import * as path19 from "node:path";
 import { fileURLToPath as fileURLToPath5 } from "node:url";
 
 // src/core/service-initialization.ts
@@ -10814,7 +10944,7 @@ function delimiterRegex(word) {
   return new RegExp(`(^|\\n)([ \\t]*(?:#{1,6}[ \\t]*|>[ \\t]*|\\*\\*[ \\t]*)?)${word}\\b`, "i");
 }
 function splitCoverageDigest(report) {
-  if (!report) return { digest: "", body: report ?? "" };
+  if (!report) return { digest: "", body: report };
   const headerMatch = delimiterRegex(COVERAGE_DIGEST_HEADER).exec(report);
   if (!headerMatch) return { digest: "", body: report };
   const lineStart = headerMatch.index + headerMatch[1].length;
@@ -11193,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;
@@ -11540,14 +11675,24 @@ ${previousQueries.map((q) => `- ${q}`).join("\n")}
         complexity,
         observer
       };
-      const responseText = isRouter ? await this.callLead({
-        ...callOptions,
-        systemPrompt: populate(""),
-        userMessage: buildRouterMessage(...this.buildRouterEvidence(options, round), runContext),
-        maxTokens: ROUTER_MAX_TOKENS,
-        component: "router",
-        label: "router-updatePlanForRound"
-      }) : await this.synthesizeCorpus({ ...callOptions, reports, runContext, populate });
+      const responseText = isRouter ? await (() => {
+        const routerMessage = buildRouterMessage(...this.buildRouterEvidence(options, round), runContext);
+        const window = model.contextWindow ?? DEFAULT_MODEL_CONTEXT_WINDOW;
+        const estimatedTokens = routerMessage.length / CHARS_PER_TOKEN + ROUTER_MAX_TOKENS + SYNTHESIS_OVERHEAD_TOKENS;
+        if (estimatedTokens > window) {
+          logger.warn(
+            `[PlanningService] Router request for ${model.id} is an estimated ${Math.round(estimatedTokens)} tokens against a ${window}-token context window (evidence ${routerMessage.length} chars, output ceiling ${ROUTER_MAX_TOKENS} tokens). Unlike the synthesizer, the router has no reduce path for an over-budget round \u2014 sending it anyway, the provider may reject this request.`
+          );
+        }
+        return this.callLead({
+          ...callOptions,
+          systemPrompt: populate(""),
+          userMessage: routerMessage,
+          maxTokens: ROUTER_MAX_TOKENS,
+          component: "router",
+          label: "router-updatePlanForRound"
+        });
+      })() : await this.synthesizeCorpus({ ...callOptions, reports, runContext, populate });
       let plan = null;
       try {
         plan = this.parseJsonPlan(responseText);
@@ -11795,6 +11940,13 @@ ${previousQueries.map((q) => `- ${q}`).join("\n")}
         `[PlanningService] Synthesis corpus is still ${finalSize} chars after ${MAX_SYNTHESIS_REDUCE_PASSES} reduce pass(es), over the ${budgetChars}-char budget for ${args.model.id}. Sending it anyway \u2014 the provider may reject this request.`
       );
     }
+    const window = args.model.contextWindow ?? DEFAULT_MODEL_CONTEXT_WINDOW;
+    const estimatedTotalTokens = (finalSize + globalSourceList.length + runContext.length) / CHARS_PER_TOKEN + config.SYNTHESIS_MAX_TOKENS + SYNTHESIS_OVERHEAD_TOKENS;
+    if (estimatedTotalTokens > window) {
+      logger.warn(
+        `[PlanningService] Synthesis request for ${args.model.id} is an estimated ${Math.round(estimatedTotalTokens)} tokens against a ${window}-token context window (corpus ${finalSize} chars, source list ${globalSourceList.length} chars, run context ${runContext.length} chars, output ceiling ${config.SYNTHESIS_MAX_TOKENS} tokens) \u2014 the source list and/or run context are large enough on their own to overflow the window even though the reduced corpus fits its budget. Sending it anyway \u2014 the provider may reject this request.`
+      );
+    }
     return this.callLead({
       ...args,
       systemPrompt: populate(reduced ? MERGE_SYNTHESIS_SECTION : ""),
@@ -12175,10 +12327,13 @@ function isFullMockMode() {
 }
 var HEALTHCHECK_MIN_BUDGET_MS = 45e3 + 6e4;
 var HEALTHCHECK_NAV_ATTEMPTS = 3;
+var BROWSER_LAUNCH_TIMEOUT_MS = 9e4;
+var CONTEXT_CREATION_TIMEOUT_MS = 3e4;
+var COLD_START_ALLOWANCE_MS = BROWSER_LAUNCH_TIMEOUT_MS + CONTEXT_CREATION_TIMEOUT_MS;
 function getHealthCheckBudgetMs(config) {
   const c = config || getConfig();
   const ms = (value, fallback) => typeof value === "number" && Number.isFinite(value) ? value : fallback;
-  const longestSlotHold = Math.max(ms(c.SEARCH_TIMEOUT_MS, 45e3), ms(c.SCRAPE_TIMEOUT_MS, 15e3)) + ms(c.BROWSER_TASK_TIMEOUT_MS, 1e4);
+  const longestSlotHold = Math.max(ms(c.SEARCH_TIMEOUT_MS, 45e3), ms(c.SCRAPE_TIMEOUT_MS, 15e3)) + ms(c.BROWSER_TASK_TIMEOUT_MS, 1e4) + COLD_START_ALLOWANCE_MS;
   const probeWork = HEALTHCHECK_NAV_ATTEMPTS * Math.max(1e4, ms(c.HEALTH_CHECK_TIMEOUT_MS, 1e4));
   return Math.max(HEALTHCHECK_MIN_BUDGET_MS, longestSlotHold + probeWork);
 }
@@ -12234,9 +12389,9 @@ var BrowserClient = class {
   get targetPort() {
     return this.port;
   }
-  async request(path19, data, signal, config) {
+  async request(path20, data, signal, config) {
     const start = Date.now();
-    const operation = path19.includes("/search") ? "search" : path19.includes("/scrape") ? "browser-task" : path19.includes("/healthcheck") ? "healthcheck" : "network";
+    const operation = path20.includes("/search") ? "search" : path20.includes("/scrape") ? "browser-task" : path20.includes("/healthcheck") ? "healthcheck" : "network";
     return new Promise((resolve9, reject) => {
       const agent = getClientAgent();
       const timeoutMs = resolveClientRequestTimeoutMs(operation, config);
@@ -12261,7 +12416,7 @@ var BrowserClient = class {
           resolved = true;
           abortCleanup?.();
           controller.abort();
-          const error = new Error(`[BrowserClient] Request to ${path19} timed out after ${timeoutMs}ms (Shared queue may be deep)`);
+          const error = new Error(`[BrowserClient] Request to ${path20} timed out after ${timeoutMs}ms (Shared queue may be deep)`);
           errorTracker.trackError(error, {
             component: "browser-manager",
             operation,
@@ -12274,7 +12429,7 @@ var BrowserClient = class {
       const req = http4.request({
         hostname: "127.0.0.1",
         port: this.port,
-        path: path19,
+        path: path20,
         method: "POST",
         agent,
         signal: controller.signal,
@@ -12298,7 +12453,7 @@ var BrowserClient = class {
               const error = new Error(
                 `Browser pool leader is draining (${parsed.reason || "leadership-lost"}) \u2014 re-elect and retry`
               );
-              logger.debug(`[BrowserClient] Leader draining on ${path19}; re-election required.`);
+              logger.debug(`[BrowserClient] Leader draining on ${path20}; re-election required.`);
               errorTracker.trackError(error, {
                 component: "browser-manager",
                 operation,
@@ -12314,7 +12469,7 @@ var BrowserClient = class {
               });
               reject(error);
             } else {
-              logger.debug(`[BrowserClient] Request ${path19} completed in ${duration}ms`);
+              logger.debug(`[BrowserClient] Request ${path20} completed in ${duration}ms`);
               resolve9(parsed);
             }
           } catch (_e) {
@@ -12334,7 +12489,7 @@ var BrowserClient = class {
           resolved = true;
           clearTimeout(timer);
           abortCleanup?.();
-          const error = new Error(`[BrowserClient] Response stream error on ${path19}: ${err.message}`);
+          const error = new Error(`[BrowserClient] Response stream error on ${path20}: ${err.message}`);
           errorTracker.trackError(error, {
             component: "browser-manager",
             operation,
@@ -12353,20 +12508,20 @@ var BrowserClient = class {
         let errorMsg;
         let errorType;
         if (nodeErr.code === "ECONNRESET" || nodeErr.code === "EPIPE") {
-          errorMsg = `Browser pool socket ${path19} closed (pool likely busy or restarting) - ${err.message}`;
+          errorMsg = `Browser pool socket ${path20} closed (pool likely busy or restarting) - ${err.message}`;
           errorType = "connection_reset";
         } else if (nodeErr.code === "ECONNREFUSED") {
-          errorMsg = `Browser pool ${path19} unreachable (server restarting or torn down) - ${err.message}`;
+          errorMsg = `Browser pool ${path20} unreachable (server restarting or torn down) - ${err.message}`;
           errorType = "connection_refused";
         } else if (nodeErr.code === "ETIMEDOUT") {
-          errorMsg = `Browser pool ${path19} timed out (slow browser response) - ${err.message}`;
+          errorMsg = `Browser pool ${path20} timed out (slow browser response) - ${err.message}`;
           errorType = "timeout";
         } else {
-          errorMsg = `Browser pool ${path19} error: ${err.message}`;
+          errorMsg = `Browser pool ${path20} error: ${err.message}`;
           errorType = "unknown";
         }
         const error = new Error(errorMsg);
-        logger.error(`[BrowserClient] Request to http://127.0.0.1:${this.port}${path19} failed:`, errorMsg);
+        logger.error(`[BrowserClient] Request to http://127.0.0.1:${this.port}${path20} failed:`, errorMsg);
         errorTracker.trackError(error, {
           component: "browser-manager",
           operation,
@@ -13246,7 +13401,7 @@ var BrowserTaskScheduler = class {
     const pool = await (await this.getWorkerPoolManager()).ensurePool(config);
     const startTime = Date.now();
     const cfg = config || getConfig();
-    const timeoutMs = cfg.SEARCH_TIMEOUT_MS + cfg.BROWSER_TASK_TIMEOUT_MS;
+    const timeoutMs = cfg.SEARCH_TIMEOUT_MS + cfg.BROWSER_TASK_TIMEOUT_MS + COLD_START_ALLOWANCE_MS;
     let timeoutId;
     let dispatchedAt = 0;
     let startDeadline = () => {
@@ -13335,7 +13490,7 @@ var BrowserTaskScheduler = class {
     const startTime = Date.now();
     const cfg = config || getConfig();
     const isMocking = process.env["PI_RESEARCH_MOCK_SCRAPE"] === "true";
-    const timeoutMs = cfg.SCRAPE_TIMEOUT_MS + (isMocking ? 5e3 : cfg.BROWSER_TASK_TIMEOUT_MS);
+    const timeoutMs = cfg.SCRAPE_TIMEOUT_MS + (isMocking ? 5e3 : cfg.BROWSER_TASK_TIMEOUT_MS + COLD_START_ALLOWANCE_MS);
     let timeoutId;
     let dispatchedAt = 0;
     let startDeadline = () => {
@@ -15393,8 +15548,8 @@ var StateValidator = class {
     if (!Value4.Check(SingletonStateSchema, coerced)) {
       const errors = [...Value4.Errors(SingletonStateSchema, coerced)];
       const errorMsg = errors.map((e) => {
-        const path19 = String(e.path || "root");
-        return `${path19}: ${e.message} (${JSON.stringify(e.value)})`;
+        const path20 = String(e.path || "root");
+        return `${path20}: ${e.message} (${JSON.stringify(e.value)})`;
       }).join(", ");
       throw new Error(`Invalid state: ${errorMsg}`);
     }
@@ -17123,7 +17278,7 @@ async function performSearch(queries, config, signal, onProgress, container = ge
   metrics.increment("browser_search_orchestrations_total", 1);
   logger.log(`[Search] Orchestrating ${queries.length} queries across ${maxWorkers} worker processes...`);
   if (onProgress) onProgress(0);
-  const QUERY_TIMEOUT_MS = (config?.SEARCH_TIMEOUT_MS ?? 45e3) + (config?.BROWSER_TASK_TIMEOUT_MS ?? 1e4);
+  const QUERY_TIMEOUT_MS = (config?.SEARCH_TIMEOUT_MS ?? 45e3) + (config?.BROWSER_TASK_TIMEOUT_MS ?? 1e4) + COLD_START_ALLOWANCE_MS;
   const filteredQueries = [...new Set(queries.filter((q) => q.trim()))];
   let timeoutCount = 0;
   let errorCount = 0;
@@ -18158,28 +18313,31 @@ async function extractPdfToMarkdown(bytes) {
   }
   try {
     const doc = new WasmPdfDocument(bytes);
-    const pageCount = doc.pageCount();
-    let markdown = `# PDF Document
+    try {
+      const pageCount = doc.pageCount();
+      let markdown = `# PDF Document
 
 **Pages:** ${pageCount}
 
 `;
-    try {
-      markdown += doc.toMarkdownAll();
-    } catch {
-      for (let i = 0; i < pageCount; i++) {
-        markdown += `## Page ${i + 1}
+      try {
+        markdown += doc.toMarkdownAll();
+      } catch {
+        for (let i = 0; i < pageCount; i++) {
+          markdown += `## Page ${i + 1}
 
 ${doc.toMarkdown(i)}
 
 `;
+        }
       }
+      const pdfExtractionDuration = Date.now() - pdfExtractionStart;
+      metrics.observe("scrape_pdf_conversion_ms", pdfExtractionDuration);
+      metrics.increment("scrape_pdf_conversions_total", 1, { status: "success", pages: String(pageCount) });
+      return markdown;
+    } finally {
+      doc.free();
     }
-    doc.free();
-    const pdfExtractionDuration = Date.now() - pdfExtractionStart;
-    metrics.observe("scrape_pdf_conversion_ms", pdfExtractionDuration);
-    metrics.increment("scrape_pdf_conversions_total", 1, { status: "success", pages: String(pageCount) });
-    return markdown;
   } catch (e) {
     const msg2 = e instanceof Error ? e.message : String(e);
     logger.debug(`[Scrapers] PDF extraction failed: ${msg2}`);
@@ -18279,7 +18437,7 @@ async function scrapeWithFetch(url, signal) {
     const contentLength = response.headers.get("content-length");
     if (contentLength) {
       const size = parseInt(contentLength, 10);
-      if (contentType.includes("application/pdf") || url.toLowerCase().endsWith(".pdf")) {
+      if (contentType.includes("application/pdf") || currentUrl.toLowerCase().endsWith(".pdf")) {
         if (size > MAX_PDF_SIZE) {
           const sizeMB = Math.round(size / 1024 / 1024);
           logger.warn(`[Scrapers] PDF too large (Content-Length: ${sizeMB}MB, max 100MB), skipping`);
@@ -18301,7 +18459,7 @@ async function scrapeWithFetch(url, signal) {
         throw new Error(`HTML response too large (${sizeMB}MB, max 25MB)`);
       }
     }
-    if (contentType.includes("application/pdf") || url.toLowerCase().endsWith(".pdf")) {
+    if (contentType.includes("application/pdf") || currentUrl.toLowerCase().endsWith(".pdf")) {
       let pdfBytes;
       try {
         pdfBytes = await readBodyCapped(response, MAX_PDF_SIZE);
@@ -18541,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,
@@ -20426,14 +20584,6 @@ function createSecuritySearchTool(options) {
           details: { error: "invalid_parameters" }
         };
       }
-      const allowed = options.tracker.recordCall("security_search");
-      if (!allowed) {
-        metrics.increment("tool_security_search_calls_total", 1, { status: "rate_limited" });
-        return {
-          content: [{ type: "text", text: options.tracker.getLimitMessage("security_search") }],
-          details: { blocked: true, reason: "limit_reached" }
-        };
-      }
       const p = params;
       const terms = p.terms;
       if (terms.length === 0) {
@@ -20475,6 +20625,14 @@ function createSecuritySearchTool(options) {
         }
       }
       const maxResults = p.maxResults ?? 20;
+      const allowed = options.tracker.recordCall("security_search");
+      if (!allowed) {
+        metrics.increment("tool_security_search_calls_total", 1, { status: "rate_limited" });
+        return {
+          content: [{ type: "text", text: options.tracker.getLimitMessage("security_search") }],
+          details: { blocked: true, reason: "limit_reached" }
+        };
+      }
       metrics.increment("tool_security_search_terms_total", terms.length);
       metrics.increment("tool_security_search_databases_total", databases.length);
       let results;
@@ -20882,20 +21040,19 @@ var StackExchangeClient = class {
       }
     });
   }
+  // Pure accessor — no metrics side effects. `stackexchangeCommand()` calls this
+  // repeatedly per invocation (pre-request gate checks, success footer, error
+  // footer) purely to read current state for display; incrementing counters here
+  // used to record 2-3x the real number of quota-low/exhausted events per call.
+  // The counters are incremented once, at the single gate check that actually
+  // observes each event (see stackexchange/index.ts).
   getQuotaInfo() {
-    const info = {
+    return {
       remaining: this.quotaRemaining,
       max: this.quotaMax,
       requestCount: this.requestCount,
       lastBackoff: this.lastBackoff
     };
-    if (this.isQuotaExhausted()) {
-      metrics.increment("stackexchange_quota_exhausted_total", 1);
-    }
-    if (this.isQuotaLow()) {
-      metrics.increment("stackexchange_quota_low_total", 1);
-    }
-    return info;
   }
   isQuotaExhausted() {
     return this.quotaExhaustedAt !== null && Date.now() - this.quotaExhaustedAt < QUOTA_PROBE_COOLDOWN_MS;
@@ -21174,6 +21331,7 @@ function formatSitesCompact(sites) {
 
 // src/stackexchange/index.ts
 init_logger();
+init_metrics();
 function notify(ctx, message, type) {
   ctx.ui?.notify?.(message, type);
 }
@@ -21200,6 +21358,7 @@ async function stackexchangeCommand(options) {
   const client = getClient(config);
   try {
     if (client.isQuotaExhausted()) {
+      metrics.increment("stackexchange_quota_exhausted_total", 1);
       const quota2 = client.getQuotaInfo();
       notify(
         ctx,
@@ -21215,6 +21374,7 @@ async function stackexchangeCommand(options) {
       };
     }
     if (client.isQuotaLow()) {
+      metrics.increment("stackexchange_quota_low_total", 1);
       const quota2 = client.getQuotaInfo();
       notify(
         ctx,
@@ -21663,6 +21823,7 @@ init_http_body();
 init_logger();
 init_safe_unref();
 init_metrics();
+init_http_body();
 var DEFAULT_REQUEST_KEY = "O43z0dpjhgX20SCx4KAo";
 var BRIDGED_GLOBALS = ["window", "document", "location", "navigator", "origin"];
 function describeError(error) {
@@ -21762,7 +21923,10 @@ async function doMint(identifiers, opts) {
       body: JSON.stringify([requestKey, botguardResponse]),
       signal: opts.signal
     });
-    const integrityJson = await integrityResponse.json();
+    if (!integrityResponse.ok) {
+      throw new Error(`HTTP ${integrityResponse.status} from attestation server`);
+    }
+    const integrityJson = await readJsonCapped(integrityResponse);
     const integrityToken = integrityJson?.[0];
     if (!integrityToken) {
       throw new Error("Integrity token rejected by attestation server (likely a non-residential IP)");
@@ -21817,7 +21981,16 @@ async function fetchVideoTranscripts(videoIds, opts = {}) {
     if (log?.setLevel && log.Level) log.setLevel(log.Level.NONE);
   } catch {
   }
-  const fetchImpl = (input, init) => fetch(input, init);
+  const ssrfFetcher = await getSsrfSafeFetcher();
+  const fetchImpl = ssrfFetcher ? (input, init) => {
+    if (typeof input === "string" || input instanceof URL) {
+      return ssrfFetcher.fetch(String(input), {
+        ...init ?? {},
+        dispatcher: ssrfFetcher.dispatcher
+      });
+    }
+    return fetch(input, init);
+  } : (input, init) => fetch(input, init);
   let visitorData;
   try {
     const seed = await breaker.execute(() => withTimeout2(
@@ -21900,10 +22073,27 @@ async function fetchOne(session, videoId, contentToken, lang, timeoutMs, signal,
           const sep3 = track.base_url.includes("?") ? "&" : "?";
           const url = `${track.base_url}${sep3}fmt=json3&c=WEB&pot=${encodeURIComponent(contentToken)}`;
           const fetchSignal = createTimeoutSignal(timeoutMs, signal);
-          const response = await fetchImpl(url, {
-            signal: fetchSignal,
-            headers: { "User-Agent": "Mozilla/5.0", "Accept-Language": lang }
-          });
+          const MAX_REDIRECTS = 5;
+          let currentUrl = url;
+          let response;
+          for (let hop = 0; hop <= MAX_REDIRECTS; hop++) {
+            response = await fetchImpl(currentUrl, {
+              signal: fetchSignal,
+              redirect: "manual",
+              headers: { "User-Agent": "Mozilla/5.0", "Accept-Language": lang }
+            });
+            if (response.status >= 300 && response.status < 400) {
+              const location = response.headers.get("location");
+              if (!location) break;
+              const resolved = new URL(location, currentUrl).href;
+              assertTrustedTimedtextUrl(resolved);
+              void response.body?.cancel()?.catch(() => {
+              });
+              currentUrl = resolved;
+              continue;
+            }
+            break;
+          }
           if (!response.ok) {
             void response.body?.cancel()?.catch(() => {
             });
@@ -22008,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}`);
@@ -22085,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)}
 
 ---
 
@@ -22424,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,
@@ -22491,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({
@@ -22719,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) {
@@ -22731,7 +22923,6 @@ function endResearchSession(piSessionId, researchId) {
     } else {
       state.failures.clear();
       state.failureReasons.clear();
-      state.aborts.clear();
     }
   }
 }
@@ -22895,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()) {
@@ -22928,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";
@@ -22945,7 +23148,7 @@ ${prompt}`);
       cwd: ctx.cwd,
       ctxModel: model,
       modelRegistry: ctx.modelRegistry,
-      systemPrompt: prompt,
+      systemPrompt: researcherSystemPrompt,
       extensionCtx: ctx,
       excludeTools: mergedExclude,
       researcherId: id,
@@ -23060,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,
@@ -23167,6 +23367,7 @@ init_logger();
 init_config();
 init_text_utils();
 init_constants();
+init_research_model_resolver();
 
 // src/orchestration/headless-observer.ts
 init_logger();
@@ -23362,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.
@@ -23385,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,
@@ -23481,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,
@@ -23898,7 +24112,6 @@ var DeepResearchOrchestrator = class {
       if (!routerChoseSynthesis) {
         if (this.currentRound > lastAnnouncedRound) {
           observer?.onRoundStart?.(this.currentRound);
-          lastAnnouncedRound = this.currentRound;
         }
         observer?.onEvaluationStart?.(this.currentRound);
         observer?.onEvaluationProgress?.("evaluating");
@@ -24632,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;
@@ -24874,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}`;
@@ -24882,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}`;
@@ -25116,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)) {
@@ -25150,6 +25385,8 @@ function extractRunStats(snapshot) {
     urlsFailed,
     errors,
     tokens,
+    cacheReadTokens,
+    cacheWriteTokens,
     cost,
     toolUsage
   };
@@ -25181,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;
@@ -25201,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);
@@ -25222,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;
@@ -25303,6 +25547,10 @@ async function _doInit(options = {}) {
   }
 }
 async function initResearchSDK(options = {}) {
+  if (_shutdownPromise) {
+    await _shutdownPromise.catch(() => {
+    });
+  }
   if (isInitialized) {
     logger.warn("[SDK] Research SDK already initialized. Call shutdownResearchSDK() first if you want to re-initialize with new options.");
     return;
@@ -25653,7 +25901,7 @@ init_logger();
 init_constants();
 import { promises as fs15 } from "node:fs";
 import { homedir as homedir4, tmpdir as tmpdir4, platform as platform3 } from "node:os";
-import { join as join19, resolve as resolve5, normalize, sep as sep2 } from "node:path";
+import { join as join20, resolve as resolve5, normalize, sep as sep2 } from "node:path";
 import { randomBytes as randomBytes6 } from "node:crypto";
 var PREFERRED_SUBDIRS = [
   "research",
@@ -25724,7 +25972,7 @@ async function findPreferredSubdir(cwd) {
   for (const target of PREFERRED_SUBDIRS) {
     const match = entries.find((e) => e.toLowerCase() === target);
     if (match === void 0) continue;
-    const candidate = join19(cwd, match);
+    const candidate = join20(cwd, match);
     try {
       const stat6 = await fs15.stat(candidate);
       if (stat6.isDirectory()) return candidate;
@@ -25769,7 +26017,7 @@ async function exportResearchReport(query, result, _mode, cwd, explicitDir) {
   for (let attempt = 0; attempt < MAX_EXPORT_RETRIES; attempt++) {
     const hash = generateHash();
     const filename = `${baseFilename}-${hash}.md`;
-    const filepath = join19(targetDir, filename);
+    const filepath = join20(targetDir, filename);
     try {
       await fs15.writeFile(filepath, result, { flag: "wx" });
       logger.log(`[export] Research report saved to: ${filepath}`);
@@ -25904,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}
 `);
@@ -25966,8 +26221,8 @@ function resolvedConfigPaths() {
     configDir,
     cliIfaceEnv: getInterfaceEnvFilePath("cli"),
     piIfaceEnv: getInterfaceEnvFilePath("pi"),
-    piAuth: path18.join(agentDir, "auth.json"),
-    piModels: path18.join(agentDir, "models.json"),
+    piAuth: path19.join(agentDir, "auth.json"),
+    piModels: path19.join(agentDir, "models.json"),
     piState: getStateDir()
   };
 }
@@ -26223,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) {
@@ -26881,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);
@@ -26940,8 +27201,8 @@ Error: ${err.message}
 var _isMain = (() => {
   try {
     if (!process.argv[1]) return false;
-    const modulePath = fs17.realpathSync(path18.resolve(fileURLToPath5(import.meta.url)));
-    const invokedPath = fs17.realpathSync(path18.resolve(process.argv[1]));
+    const modulePath = fs17.realpathSync(path19.resolve(fileURLToPath5(import.meta.url)));
+    const invokedPath = fs17.realpathSync(path19.resolve(process.argv[1]));
     return modulePath === invokedPath;
   } catch {
     return false;
@@ -26968,6 +27229,7 @@ export {
   cmdKnowledgeConfig,
   cmdResearch,
   exitCodeForSignal,
+  makeProgressObserver,
   parseArgs,
   reportError
 };