@lincoln504/pi-research 1.0.12 → 1.1.2

package/README.md

@@ -3,7 +3,7 @@
 </p>
 
 <p align="center">
-  <strong>Limitless research and knowledge store — for pi, agent skill, or SDK.</strong>
+  <strong>Local web research and knowledge store</strong>
 </p>
 
 <p align="center">
@@ -24,9 +24,20 @@
 
 <a href="https://github.com/Lincoln504/pi-research/actions/workflows/ci.yml"><img alt="Build status" src="https://img.shields.io/github/actions/workflow/status/Lincoln504/pi-research/ci.yml?style=flat-square&branch=main" /></a> <a href="https://www.npmjs.com/package/@lincoln504/pi-research"><img alt="npm version" src="https://img.shields.io/npm/v/@lincoln504/pi-research.svg?style=flat-square" /></a>
 
-Research is broken into subtasks automatically, with each sub-researcher given a high volume of sources to investigate. Then, evaluator decides whether the answer is complete or an additional round of research is needed. The final result is a synthesized cited report.
+**Free, unlimited web search &amp; scraping — no monthly quota, no subscription.**
+You pay only for the LLM tokens you use, and it builds your own private, searchable
+knowledge store on your machine.
 
-Ask in natural language — the tool understands the depth needed:
+### How it works
+
+A research run is a loop of agent teams: a coordinator plans the work and runs an
+opening search, parallel researcher agents scrape and read sources through a fixed,
+sandboxed toolkit (no shell access, and no ability to write or modify files), and an evaluator decides whether
+to run another round or synthesize — returning one cited Markdown report while its
+sources are saved to the knowledge store in the background.
+
+Three depth levels — normal, deep, ultra — set the team size and number of rounds;
+ask in natural language and the tool picks the right one:
 
 ![Prompt-driven multi-round research in the pi TUI](docs/media/02-prompt-research.gif)
 
@@ -39,12 +50,13 @@ Ask in natural language — the tool understands the depth needed:
 - Using the pi-research agent skill as OpenClaw's web access.
 - Building agent systems that identify and examine web sources.
 
-### Advantages
+### Why pi-research
 
-- Unlimited search and scrape, for free — you only pay for LLM tokens.
-- Context-efficient — it returns a synthesized, cited report to the chat instead of dumping raw web content into the conversation.
-- Safe by design — web access runs inside a specialized, limited research agent with no filesystem or shell access.
-- Search a little or a lot — three depth levels in the pi tool (four via the SDK and standalone CLI, which add the quick depth-0 path). Levels 1 and 2 are recommended for everyday workflow use; level 3 is for larger-scale investigations.
+- **Free, unlimited search &amp; scrape — no quota, no monthly fee.** Most AI-search providers cap free searches per month and then charge; results run on *their* index on *their* servers. pi-research's search and scraping layer (DuckDuckGo via a stealth browser) is free and unlimited — you pay only for the LLM tokens you use, never per search or per month.
+- **You own your index.** Every finding is written into a local [LanceDB](https://lancedb.com) knowledge store on *your* machine — a persistent, searchable index you control and keep, which also seeds future runs so repeat questions get faster, cheaper answers. No borrowed, server-side index you can't keep or query. Findings can also be kept **globally**, scoped to a **single project**, or **not kept at all** — set per directory, changed whenever you like. The optionality is the point: the store is yours to build, partition, or switch off.
+- **Cited reports, not raw dumps.** It returns one synthesized, sourced Markdown report to the chat instead of dumping raw web content into the conversation — context-efficient and easy to verify.
+- **Sandboxed by design.** Web access runs inside a specialized, limited research agent that cannot run shell commands or write, edit, or delete anything. It can read and search files in the working directory, so scope that directory as you would for any coding agent.
+- **Search a little or a lot** — three depth levels in the pi tool (four via the SDK and standalone CLI, which add the quick depth-0 path). Levels 1 and 2 are recommended for everyday workflow use; level 3 is for larger-scale investigations.
 
 ### Requirements / limitations
 

package/dist/cli.mjs

@@ -1709,9 +1709,23 @@ var init_metrics = __esm({
 });
 
 // src/utils/llm-usage.ts
+function warnIfUnpriced(model, tokens, cost) {
+  if (tokens <= 0 || cost > 0) return;
+  const m = model;
+  const key = `${m.provider ?? "unknown"}/${m.id ?? "unknown"}`;
+  if (unpricedModelsWarned.has(key)) return;
+  const table = m.cost;
+  const allZero = !table || Object.values(table).every((v) => typeof v !== "number" || v === 0);
+  if (!allZero) return;
+  unpricedModelsWarned.add(key);
+  logger.warn(
+    `[LlmUsage] Model "${key}" consumed ${tokens} tokens but reports $0.00 \u2014 its price table is all zeros. Expected for flat-rate plans and local servers. Otherwise the price data is missing: a hand-written "models" entry in ~/.pi/agent/models.json replaces pi's catalog entry (and its pricing) for the same model id \u2014 remove it and let pi's catalog supply the model, or use "modelOverrides", which merges.`
+  );
+}
 function recordLlmUsage(model, rawUsage, opts) {
   if (!rawUsage) return { tokens: 0, cost: 0 };
   const { tokens, cost } = extractUsage(model, rawUsage);
+  warnIfUnpriced(model, tokens, cost);
   if (tokens > 0 || cost > 0) {
     const labels = { component: opts.component };
     if (opts.complexity !== void 0) labels["complexity"] = String(opts.complexity);
@@ -1721,11 +1735,14 @@ function recordLlmUsage(model, rawUsage, opts) {
   }
   return { tokens, cost };
 }
+var unpricedModelsWarned;
 var init_llm_usage = __esm({
   "src/utils/llm-usage.ts"() {
     "use strict";
     init_llm();
+    init_logger();
     init_metrics();
+    unpricedModelsWarned = /* @__PURE__ */ new Set();
   }
 });
 
@@ -3292,6 +3309,13 @@ function constructMinimalModel(provider, modelId, _apiKey) {
     // Provider-specific base URLs are handled by pi-ai internal registry
     reasoning: false,
     input: ["text"],
+    // No catalog is available on this path, so there is no price data and no real
+    // context/output ceiling to read. The zeros below are "unknown", NOT "free":
+    // cost reporting for this model will read $0.00 (see warnIfUnpriced in
+    // utils/llm-usage.ts), and the window figures are conservative guesses, not the
+    // model's true limits — so docs/CONFIGURATION.md's "clamped to the model's real
+    // ceiling" guarantee does not hold here. Anyone relying on accurate cost or the
+    // full context window should give pi a credential so it can fetch the real catalog.
     cost: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0 },
     contextWindow: 128e3,
     maxTokens: 32768,
@@ -3309,7 +3333,7 @@ function resolveModel(registry, modelSpec, provider, apiKey) {
       if (apiKey && provider) {
         return constructMinimalModel(prov, modelId, apiKey);
       }
-      throw new Error(`Model "${modelSpec}" not found in pi's configured model registry. Check ${path6.join(getAgentDir(), "models.json")}.`);
+      throw new Error(buildModelNotFoundMessage(modelSpec));
     }
     const allModels = safeGetAll(registry);
     const sameId = allModels.filter((m) => m.id === modelSpec);
@@ -3340,9 +3364,23 @@ function resolveModel(registry, modelSpec, provider, apiKey) {
     }
     return constructMinimalModel(provider, modelSpec, apiKey);
   }
-  throw new Error(
-    `No LLM model available. Please configure your model registry (${path6.join(getAgentDir(), "models.json")}) or provide an explicit apiKey.`
-  );
+  throw new Error(buildNoModelAvailableMessage());
+}
+function credentialGuidance() {
+  const agentDir = getAgentDir();
+  return `  \u2022 Provider pi supports built-in (openrouter, anthropic, openai, \u2026): add a credential \u2014 run \`pi\` and use /login, set the provider's API-key environment variable, or add it to ${path6.join(agentDir, "auth.json")}. pi then fetches that provider's model catalog automatically.
+  \u2022 Custom or self-hosted provider (Ollama, vLLM, a proxy): declare it in ${path6.join(agentDir, "models.json")}.
+    Note: a models.json entry REPLACES pi's catalog entry for the same model id, discarding its pricing and
+    context/output limits. To adjust a single field of a built-in model, use "modelOverrides" instead \u2014 it merges.`;
+}
+function buildModelNotFoundMessage(modelSpec) {
+  return `Model "${modelSpec}" not found in pi's model registry.
+${credentialGuidance()}`;
+}
+function buildNoModelAvailableMessage() {
+  return `No LLM model available.
+${credentialGuidance()}
+  \u2022 Or pass an explicit apiKey.`;
 }
 function readModelsJsonProviderOrder() {
   const modelsJsonPath = path6.join(getAgentDir(), "models.json");
@@ -3428,6 +3466,7 @@ function withTimeout2(promise, timeoutMs, label, signal) {
   logger.debug(`[withTimeout] Starting ${timeoutMs}ms timeout guard (external signal: ${signal?.aborted ?? "no signal"})`);
   return new Promise((resolve8, reject) => {
     if (combinedSignal.aborted) {
+      void promise.catch(() => void 0);
       logger.debug(`[withTimeout] ${label} already aborted at start (external cancellation)`);
       return reject(new Error(`${label} cancelled or timed out`));
     }
@@ -3533,7 +3572,7 @@ async function retryWithBackoff(fn, options = {}) {
       metrics.observe("retry_backoff_delay_ms", delay2, { attempt: String(attempt), label: opts.label });
       logger.warn(`[Retry] ${opts.label} failed (attempt ${attempt + 1}/${opts.maxRetries + 1}), retrying in ${Math.round(delay2)}ms: ${lastError.message}`);
       try {
-        await abortableDelay(delay2, opts.signal);
+        await abortableDelay(delay2, opts.signal, true);
       } catch {
         metrics.increment("retry_aborted_total", 1, { label: opts.label });
         throw lastError;
@@ -4052,6 +4091,11 @@ var init_circuit_breaker = __esm({
           metrics.observe("circuit_breaker_call_duration_ms", duration, { breaker: this.options.name, status: "error" });
           if (this.options.isTransientError(error)) {
             this.onFailure(error);
+          } else if (admittedAsProbe && this.state === "HALF_OPEN") {
+            logger.warn(
+              `[CircuitBreaker] '${this.options.name}' HALF_OPEN probe failed with a non-counted error; treating as inconclusive and re-opening: ${error instanceof Error ? error.message : String(error)}`
+            );
+            this.transitionTo("OPEN");
           }
           throw error;
         } finally {
@@ -8039,7 +8083,7 @@ function resolveResearchModel(options) {
   if (anyModel.length > 0) {
     return pickPreferredAvailable(anyModel, readModelsJsonProviderOrder());
   }
-  throw new Error("No LLM model available for research. Please configure your model registry (~/.pi/agent/models.json).");
+  throw new Error(buildNoModelAvailableMessage());
 }
 var init_research_model_resolver = __esm({
   "src/core/llm/research-model-resolver.ts"() {
@@ -8341,7 +8385,7 @@ async function runBackgroundExtraction(model, auth, conversationHistory, queries
       const delay2 = KNOWLEDGE_SYNTHESIS_RETRY_BASE_MS * attempt;
       metrics.increment("research_knowledge_search_synthesis_retries_total", 1);
       logger.warn(`[research-knowledge-search] Synthesis attempt ${attempt}/${KNOWLEDGE_SYNTHESIS_MAX_ATTEMPTS} failed transiently (${msg2}); retrying in ${delay2}ms`);
-      await abortableDelay(delay2, signal);
+      await abortableDelay(delay2, signal, true);
     }
   }
   const extracted = extractJson(responseText, "object");
@@ -8429,7 +8473,7 @@ ${desc}`;
       const delay2 = KNOWLEDGE_SYNTHESIS_RETRY_BASE_MS * attempt;
       metrics.increment("research_knowledge_search_triage_retries_total", 1);
       logger.warn(`[research-knowledge-search] Triage attempt ${attempt}/${KNOWLEDGE_SYNTHESIS_MAX_ATTEMPTS} failed transiently (${msg2}); retrying in ${delay2}ms`);
-      await abortableDelay(delay2, signal);
+      await abortableDelay(delay2, signal, true);
     }
   }
   const extracted = extractJson(responseText, "object");
@@ -9557,11 +9601,11 @@ function normalizeCitations(reports) {
     });
     const headerIdx = lastCitedLinksHeaderIndex(report);
     let content = headerIdx >= 0 ? report.slice(0, headerIdx) : report;
-    content = content.replace(/\[(\d+)\]/g, (match, p1) => {
-      const localId = parseInt(p1, 10);
-      const globalId = localToGlobal.get(localId);
-      return globalId !== void 0 ? `[${globalId}]` : match;
-    });
+    content = rewriteCitationMarkers(
+      content,
+      localToGlobal,
+      (n) => !localToGlobal.has(n)
+    );
     normalizedReports.set(id, content.trim());
   }
   return { normalizedReports, globalCitations };
@@ -9576,6 +9620,42 @@ function formatCitedLinks(citations) {
   return `CITED LINKS
 ${links.join("\n")}`;
 }
+var MAX_PLAUSIBLE_CITATION_MARKER = 200;
+function rewriteCitationMarkers(text, remap, isDangling) {
+  const inFence = fencedCodeMask(text);
+  return text.replace(/([ \t]*)\[(\d+)\]/g, (match, pad, digits, offset) => {
+    const n = parseInt(digits, 10);
+    const mapped = remap.get(n);
+    if (mapped !== void 0) return `${pad}[${mapped}]`;
+    if (n < 1 || n > MAX_PLAUSIBLE_CITATION_MARKER || !isDangling(n)) return match;
+    if (inFence(offset) || inInlineCodeSpan(text, offset)) return match;
+    const lineStart = text.lastIndexOf("\n", offset - 1) + 1;
+    return text.slice(lineStart, offset).trim() === "" ? pad : "";
+  });
+}
+function fencedCodeMask(text) {
+  const ranges = [];
+  let open4 = -1;
+  let pos = 0;
+  for (const line of text.split("\n")) {
+    if (/^\s{0,3}(```|~~~)/.test(line)) {
+      if (open4 < 0) open4 = pos;
+      else {
+        ranges.push([open4, pos + line.length]);
+        open4 = -1;
+      }
+    }
+    pos += line.length + 1;
+  }
+  if (open4 >= 0) ranges.push([open4, text.length]);
+  return (offset) => ranges.some(([start, end]) => offset >= start && offset < end);
+}
+function inInlineCodeSpan(text, offset) {
+  const lineStart = text.lastIndexOf("\n", offset - 1) + 1;
+  let ticks = 0;
+  for (let i = lineStart; i < offset; i++) if (text[i] === "`") ticks++;
+  return ticks % 2 === 1;
+}
 
 // src/core/planning-service.ts
 init_agentic_repair();
@@ -10813,7 +10893,12 @@ function isServerDrainingError(error) {
 function isPoolShutdownError(error) {
   if (!error || typeof error !== "object") return false;
   const err = error;
-  return typeof err.message === "string" && (err.message.includes("Worker pool is shutting down") || err.message.includes("Cannot execute a task on destroying pool") || err.message.includes("destroying pool"));
+  return typeof err.message === "string" && (err.message.includes("Worker pool is shutting down") || err.message.includes("Cannot execute a task on destroying pool") || err.message.includes("destroying pool") || // worker-pool-manager throws this when auto-recovery is still swapping the
+  // pool. Its own text says "please retry", but until it was listed here no
+  // classifier matched it, so the first attempt rethrew instead of retrying —
+  // and auto-recovery fires only after 3 consecutive worker failures, i.e.
+  // exactly when a burst of tasks is in flight and would all die together.
+  err.message.includes("Worker pool is being reset"));
 }
 var sessionCircuitBreakers = /* @__PURE__ */ new Map();
 var MAX_SESSION_BREAKERS = 256;
@@ -14228,14 +14313,14 @@ init_file_lock_service();
 init_service_registry();
 init_service_names();
 import * as pathmod2 from "node:path";
-var DEFAULT_MAX_CONCURRENT_RUNS = 2;
-var DEFAULT_ACQUIRE_TIMEOUT_MS = 0;
+var DEFAULT_MAX_CONCURRENT_RUNS = 3;
+var DEFAULT_ACQUIRE_TIMEOUT_MS = 6e5;
 var POLL_DELAY_MS = 250;
 var ResearchRunCapacityError = class extends Error {
   slots;
   constructor(slots, maxWaitMs) {
     super(
-      `Maximum concurrent research runs (${slots}) reached${maxWaitMs > 0 ? ` after waiting ${maxWaitMs}ms` : ""}; wait for an in-progress run to finish and retry. (Override with PI_RESEARCH_MAX_CONCURRENT_RUNS.)`
+      `Maximum concurrent research runs (${slots}) reached${maxWaitMs > 0 ? ` and still busy after queueing for ${Math.round(maxWaitMs / 1e3)}s` : ""}; another run is still in progress. This is temporary \u2014 retry shortly. (Raise the cap with PI_RESEARCH_MAX_CONCURRENT_RUNS, or the queue wait with PI_RESEARCH_RUN_ACQUIRE_TIMEOUT_MS.)`
     );
     this.name = "ResearchRunCapacityError";
     this.slots = slots;
@@ -14335,16 +14420,20 @@ var ResearchRunSemaphore = class {
    * @param signal aborts the wait. Without it a run started under a long
    *   `PI_RESEARCH_RUN_ACQUIRE_TIMEOUT_MS` would ignore Ctrl-C until the deadline
    *   passed, because the wait happens before any orchestrator exists to cancel.
+   * @param onQueued invoked at most once, when the first full sweep finds every
+   *   slot busy and the call is about to wait. Lets a front-end tell the user the
+   *   run is queued rather than hung. Never allowed to break the acquire.
    * @throws {ResearchRunCapacityError} if no slot frees within `maxWaitMs`.
    * @throws {Error} named `AbortError` if `signal` aborts while waiting.
    */
-  async acquire(maxWaitMs = this.defaultMaxWaitMs, signal) {
+  async acquire(maxWaitMs = this.defaultMaxWaitMs, signal, onQueued) {
     if (!this._initialized) await this.initialize();
     if (signal?.aborted) {
       metrics.increment("research_run_acquire_total", 1, { status: "aborted" });
       throwIfAborted(signal);
     }
     const deadline = Date.now() + Math.max(0, maxWaitMs);
+    let announcedQueued = false;
     for (; ; ) {
       const start = this.nextStartIndex;
       this.nextStartIndex = (this.nextStartIndex + 1) % this.maxSlots;
@@ -14361,6 +14450,15 @@ var ResearchRunSemaphore = class {
         metrics.increment("research_run_acquire_total", 1, { status: "exhausted" });
         throw new ResearchRunCapacityError(this.maxSlots, maxWaitMs);
       }
+      if (!announcedQueued) {
+        announcedQueued = true;
+        logger.info(`[ResearchRunSemaphore] All ${this.maxSlots} run slot(s) busy \u2014 queueing for up to ${maxWaitMs}ms.`);
+        try {
+          onQueued?.(this.maxSlots, maxWaitMs);
+        } catch (err) {
+          logger.debug(`[ResearchRunSemaphore] onQueued callback threw: ${err instanceof Error ? err.message : String(err)}`);
+        }
+      }
       try {
         await sleep(POLL_DELAY_MS, signal);
       } catch (err) {
@@ -14886,6 +14984,17 @@ init_service_registry();
 init_service_interfaces();
 var lastRestartTime = 0;
 var RESTART_COOLDOWN_MS = 1e4;
+var LEADER_HANDOVER_RETRIES = 3;
+var HANDOVER_BACKOFF_MS = 1200;
+async function recoverFromLeaderHandover(container) {
+  logger.warn("[BrowserManager] Leader handover detected (pool draining) \u2014 dropping stale scheduler handle and re-resolving...");
+  await forceSchedulerRestart2(false, container).catch(
+    (err) => logger.debug("[BrowserManager] Scheduler re-resolve during handover failed (non-fatal):", err)
+  );
+  await waitForBrowserPoolIdle(15e3).catch(
+    (err) => logger.debug("Wait for browser idle timed out or failed:", err)
+  );
+}
 async function getScheduler2(config, container = getServiceContainer()) {
   try {
     const factory = await getService(ServiceNames.SCHEDULER_FACTORY, void 0, container);
@@ -14902,7 +15011,7 @@ async function forceSchedulerRestart2(forceClearRemoteState = false, container =
     return await forceSchedulerRestart(forceClearRemoteState, container);
   }
 }
-async function runBrowserTask(taskOrUrl, type = "scrape", config, signal, retries = 1, container = getServiceContainer()) {
+async function runBrowserTask(taskOrUrl, type = "scrape", config, signal, retries = 1, container = getServiceContainer(), handoverRetries = LEADER_HANDOVER_RETRIES) {
   if (signal?.aborted) throw new Error("Aborted");
   const sessionId = typeof taskOrUrl === "object" ? taskOrUrl.sessionId : void 0;
   const breaker2 = sessionId ? getBrowserCircuitBreaker(sessionId) : browserCircuitBreaker;
@@ -14923,6 +15032,19 @@ async function runBrowserTask(taskOrUrl, type = "scrape", config, signal, retrie
     });
   } catch (error) {
     if (signal?.aborted || error instanceof Error && error.message === "Aborted") throw new Error("Aborted", { cause: error });
+    const isHandover = isPoolShutdownError(error) && !isTaskTimeoutError(error) && !isCloudflareBlockError(error);
+    if (isHandover && handoverRetries > 0) {
+      errorTracker.trackError(error, {
+        component: "browser-manager",
+        operation: type,
+        taskType: type,
+        errorType: "leader_handover"
+      });
+      logger.warn(`[BrowserManager] Leader handover during ${type} task (handover attempts left: ${handoverRetries}): ${(error instanceof Error ? error.message : String(error)).substring(0, 100)}...`);
+      await recoverFromLeaderHandover(container);
+      await new Promise((resolve8) => setTimeout(resolve8, HANDOVER_BACKOFF_MS + Math.floor(Math.random() * 400)));
+      return runBrowserTask(taskOrUrl, type, config, signal, retries, container, handoverRetries - 1);
+    }
     if (retries > 0 && isTransientSocketError(error) && !isTaskTimeoutError(error) && !isCloudflareBlockError(error)) {
       errorTracker.trackError(error, {
         component: "browser-manager",
@@ -14948,7 +15070,7 @@ async function runBrowserTask(taskOrUrl, type = "scrape", config, signal, retrie
       }
       const jitter = 100 + Math.floor(Math.random() * 400);
       await new Promise((resolve8) => setTimeout(resolve8, jitter));
-      return runBrowserTask(taskOrUrl, type, config, signal, retries - 1, container);
+      return runBrowserTask(taskOrUrl, type, config, signal, retries - 1, container, handoverRetries);
     }
     throw error;
   }
@@ -14968,7 +15090,7 @@ async function runBrowserHealthCheck(config, retries = 1, signal, container = ge
       });
       logger.warn(`[BrowserManager] Transient socket error during healthcheck (retries left: ${retries}): ${(error instanceof Error ? error.message : String(error)).substring(0, 100)}...`);
       if (isPoolShutdownError(error)) {
-        await waitForBrowserPoolIdle(15e3).catch((err) => logger.debug("Wait for browser idle timed out or failed:", err));
+        await recoverFromLeaderHandover(container);
       } else {
         const now = Date.now();
         if (now - lastRestartTime > RESTART_COOLDOWN_MS) {
@@ -14987,7 +15109,7 @@ async function runBrowserHealthCheck(config, retries = 1, signal, container = ge
     throw error;
   }
 }
-async function runWorkerSearch(query, config, signal, retries = 1, sessionId, container = getServiceContainer()) {
+async function runWorkerSearch(query, config, signal, retries = 1, sessionId, container = getServiceContainer(), handoverRetries = LEADER_HANDOVER_RETRIES) {
   if (signal?.aborted) throw new Error("Aborted");
   const breaker2 = sessionId ? getBrowserCircuitBreaker(sessionId) : browserCircuitBreaker;
   try {
@@ -14998,6 +15120,19 @@ async function runWorkerSearch(query, config, signal, retries = 1, sessionId, co
     });
   } catch (error) {
     if (signal?.aborted || error instanceof Error && error.message === "Aborted") throw new Error("Aborted", { cause: error });
+    const isHandover = isPoolShutdownError(error) && !isTaskTimeoutError(error) && !isCloudflareBlockError(error);
+    if (isHandover && handoverRetries > 0) {
+      errorTracker.trackError(error, {
+        component: "browser-manager",
+        operation: "search",
+        query,
+        errorType: "leader_handover"
+      });
+      logger.warn(`[BrowserManager] Leader handover during search (handover attempts left: ${handoverRetries}): ${(error instanceof Error ? error.message : String(error)).substring(0, 100)}...`);
+      await recoverFromLeaderHandover(container);
+      await new Promise((resolve8) => setTimeout(resolve8, HANDOVER_BACKOFF_MS + Math.floor(Math.random() * 400)));
+      return runWorkerSearch(query, config, signal, retries, sessionId, container, handoverRetries - 1);
+    }
     if (retries > 0 && isTransientSocketError(error) && !isTaskTimeoutError(error) && !isCloudflareBlockError(error)) {
       errorTracker.trackError(error, {
         component: "browser-manager",
@@ -15021,7 +15156,7 @@ async function runWorkerSearch(query, config, signal, retries = 1, sessionId, co
       }
       const jitter = 100 + Math.floor(Math.random() * 400);
       await new Promise((resolve8) => setTimeout(resolve8, jitter));
-      return runWorkerSearch(query, config, signal, retries - 1, sessionId, container);
+      return runWorkerSearch(query, config, signal, retries - 1, sessionId, container, handoverRetries);
     }
     throw error;
   }
@@ -20813,6 +20948,9 @@ var HeadlessObserver = class {
   onStart(query, complexity) {
     this.emit("start", { query, complexity });
   }
+  onRunQueued(slots, maxWaitMs) {
+    this.emit("run_queued", { slots, maxWaitMs });
+  }
   onPlanningStart(attempt) {
     this.emit("planning_start", { attempt });
   }
@@ -21611,7 +21749,9 @@ var ResearchOrchestrationService = class {
     try {
       const container = tryGetServiceContainerFromCtx(ctx);
       const semaphore = await getService(ServiceNames.RESEARCH_RUN_SEMAPHORE, ctx, container);
-      runSlot = await semaphore.acquire(void 0, signal);
+      runSlot = await semaphore.acquire(void 0, signal, (slots, maxWaitMs) => {
+        notifyRunQueued(observer, slots, maxWaitMs);
+      });
       logger.info(`[ResearchOrchestrationService] Acquired research run slot ${runSlot.slotIndex} (cap ${semaphore.getMaxSlots()}).`);
     } catch (err) {
       if (err instanceof ResearchRunCapacityError) throw err;
@@ -21965,6 +22105,15 @@ var ResearchOrchestrationService = class {
     }
   }
 };
+function notifyRunQueued(observer, slots, maxWaitMs) {
+  try {
+    const obs = observer;
+    if (typeof obs?.onRunQueued === "function") obs.onRunQueued(slots, maxWaitMs);
+    else if (typeof obs?.onProgress === "function") obs.onProgress("run_queued", { slots, maxWaitMs });
+  } catch (err) {
+    logger.debug(`[ResearchOrchestrationService] run_queued notification threw: ${err instanceof Error ? err.message : String(err)}`);
+  }
+}
 
 // src/orchestration/research-session-service.ts
 init_logger();
@@ -22114,42 +22263,6 @@ 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 MAX_PLAUSIBLE_CITATION_MARKER = 200;
-function rewriteCitationMarkers(text, remap, isDangling) {
-  const inFence = fencedCodeMask(text);
-  return text.replace(/([ \t]*)\[(\d+)\]/g, (match, pad, digits, offset) => {
-    const n = parseInt(digits, 10);
-    const mapped = remap.get(n);
-    if (mapped !== void 0) return `${pad}[${mapped}]`;
-    if (n < 1 || n > MAX_PLAUSIBLE_CITATION_MARKER || !isDangling(n)) return match;
-    if (inFence(offset) || inInlineCodeSpan(text, offset)) return match;
-    const lineStart = text.lastIndexOf("\n", offset - 1) + 1;
-    return text.slice(lineStart, offset).trim() === "" ? pad : "";
-  });
-}
-function fencedCodeMask(text) {
-  const ranges = [];
-  let open4 = -1;
-  let pos = 0;
-  for (const line of text.split("\n")) {
-    if (/^\s{0,3}(```|~~~)/.test(line)) {
-      if (open4 < 0) open4 = pos;
-      else {
-        ranges.push([open4, pos + line.length]);
-        open4 = -1;
-      }
-    }
-    pos += line.length + 1;
-  }
-  if (open4 >= 0) ranges.push([open4, text.length]);
-  return (offset) => ranges.some(([start, end]) => offset >= start && offset < end);
-}
-function inInlineCodeSpan(text, offset) {
-  const lineStart = text.lastIndexOf("\n", offset - 1) + 1;
-  let ticks = 0;
-  for (let i = lineStart; i < offset; i++) if (text[i] === "`") ticks++;
-  return ticks % 2 === 1;
-}
 function redactUnverifiedProseUrls(text, trusted) {
   if (trusted.size === 0) return text;
   let removed = 0;
@@ -23191,8 +23304,8 @@ function appendExportMessage(result, filepath, totalCost) {
 ---
 
 Research report saved to: ${filepath}`;
-  if (totalCost !== void 0 && totalCost > 0) {
-    const costStr = totalCost < 0.01 ? "<$0.01" : `$${totalCost.toFixed(4)}`.replace(/0+$/, "").replace(/\.$/, "");
+  if (totalCost !== void 0) {
+    const costStr = totalCost === 0 ? "$0.00" : totalCost < 0.01 ? "<$0.01" : `$${totalCost.toFixed(4)}`.replace(/0+$/, "").replace(/\.$/, "");
     footer += `
 Total cost: ${costStr}`;
   }
@@ -23221,7 +23334,15 @@ var EXIT = {
   /** Missing setup: package, model, or API key not configured. */
   CONFIG: 78,
   /** Something went wrong at runtime (network, provider, internal). */
-  SOFTWARE: 70
+  SOFTWARE: 70,
+  /**
+   * Temporary failure — the request was well-formed and the install is healthy,
+   * but the machine is at capacity right now (all research run slots held by
+   * live runs). Distinct from SOFTWARE so a calling agent can tell "busy, try
+   * again shortly" apart from "this run crashed" and back off instead of
+   * re-running a broken command.
+   */
+  TEMPFAIL: 75
 };
 function toStderr(s) {
   process.stderr.write(s);
@@ -23241,6 +23362,12 @@ function makeProgressObserver() {
           toStderr(`  \u2022 plan: ${data?.plan?.researchers?.length ?? "?"} researcher(s)
 `);
           break;
+        case "run_queued":
+          toStderr(
+            `  \u2022 queued: ${data?.slots ?? "?"} concurrent run(s) already active \u2014 waiting up to ${Math.round((data?.maxWaitMs ?? 0) / 1e3)}s for a slot\u2026
+`
+          );
+          break;
         case "round_start":
           toStderr(`  \u2022 round ${data?.round}
 `);
@@ -23261,10 +23388,16 @@ function makeProgressObserver() {
           toStderr(`  \u2022 evaluator: ${data?.action}
 `);
           break;
-        case "tokens_consumed":
-          if (data?.cost) toStderr(`  \u2022 tokens: ${data?.tokens ?? 0} ($${Number(data.cost).toFixed(4)})
+        case "tokens_consumed": {
+          const consumed = Number(data?.tokens ?? 0);
+          const costVal = typeof data?.cost === "number" ? data.cost : void 0;
+          if (consumed > 0 || costVal !== void 0) {
+            const costPart = costVal === void 0 ? "" : ` ($${costVal.toFixed(4)})`;
+            toStderr(`  \u2022 tokens: ${consumed}${costPart}
 `);
+          }
           break;
+        }
         case "complete":
           toStderr(`  \u2022 complete (${data?.result?.length ?? 0} chars)
 `);
@@ -23785,17 +23918,25 @@ async function reportError(err, what, json) {
   const msg2 = err instanceof Error ? err.message : String(err);
   const lower = msg2.toLowerCase();
   const isTaggedResearchStop = err?.code === RESEARCH_STOPPED_ERROR_CODE;
-  const isConfigError = !isTaggedResearchStop && (lower.includes("no llm model available") || lower.includes("not found in pi") || lower.includes("no api key") || lower.includes("provider must be specified") || lower.includes("invalid model string") || lower.includes("authentication") || lower.includes("unauthorized") || lower.includes("api key"));
+  const isCapacity = err instanceof Error && err.name === "ResearchRunCapacityError";
+  const isConfigError = !isTaggedResearchStop && !isCapacity && (lower.includes("no llm model available") || lower.includes("not found in pi") || lower.includes("no api key") || lower.includes("provider must be specified") || lower.includes("invalid model string") || lower.includes("authentication") || lower.includes("unauthorized") || lower.includes("api key"));
   const isRateLimit = lower.includes("429") || lower.includes("rate limit") || lower.includes("too many requests");
-  const exitCode = isConfigError && !isRateLimit ? EXIT.CONFIG : EXIT.SOFTWARE;
+  const exitCode = isCapacity ? EXIT.TEMPFAIL : isConfigError && !isRateLimit ? EXIT.CONFIG : EXIT.SOFTWARE;
   if (json) {
     const payload = { ok: false, error: msg2, exitCode };
+    if (isCapacity || isRateLimit) payload["retryable"] = true;
     if (process.env["PI_RESEARCH_DEBUG"] === "true" && err instanceof Error && err.stack) {
       payload["stack"] = err.stack;
     }
     toStdout(pretty(payload));
     return exitCode;
   }
+  if (isCapacity) {
+    toStderr(`
+Error: pi-research ${what} did not start: ${msg2}
+`);
+    return exitCode;
+  }
   if (isRateLimit) {
     toStderr(`
 Error: pi-research ${what} halted: provider rate limit reached. Wait a moment and retry.
@@ -23898,7 +24039,9 @@ CONFIGURE
 EXIT CODES
   0  success
   64 bad arguments
+  75 at capacity \u2014 every concurrent run slot is busy; nothing is broken, retry later
   78 not configured \u2014 message prints the exact locations to fix
+     (on \`knowledge\`, also returned when the store is deliberately disabled)
   70 runtime error (network, provider, internal)
 `;
 }

package/dist/thread-worker.mjs

@@ -1284,6 +1284,11 @@ var init_circuit_breaker = __esm({
           metrics.observe("circuit_breaker_call_duration_ms", duration, { breaker: this.options.name, status: "error" });
           if (this.options.isTransientError(error)) {
             this.onFailure(error);
+          } else if (admittedAsProbe && this.state === "HALF_OPEN") {
+            logger.warn(
+              `[CircuitBreaker] '${this.options.name}' HALF_OPEN probe failed with a non-counted error; treating as inconclusive and re-opening: ${error instanceof Error ? error.message : String(error)}`
+            );
+            this.transitionTo("OPEN");
           }
           throw error;
         } finally {
@@ -1379,7 +1384,12 @@ function isServerDrainingError(error) {
 function isPoolShutdownError(error) {
   if (!error || typeof error !== "object") return false;
   const err = error;
-  return typeof err.message === "string" && (err.message.includes("Worker pool is shutting down") || err.message.includes("Cannot execute a task on destroying pool") || err.message.includes("destroying pool"));
+  return typeof err.message === "string" && (err.message.includes("Worker pool is shutting down") || err.message.includes("Cannot execute a task on destroying pool") || err.message.includes("destroying pool") || // worker-pool-manager throws this when auto-recovery is still swapping the
+  // pool. Its own text says "please retry", but until it was listed here no
+  // classifier matched it, so the first attempt rethrew instead of retrying —
+  // and auto-recovery fires only after 3 consecutive worker failures, i.e.
+  // exactly when a burst of tasks is in flight and would all die together.
+  err.message.includes("Worker pool is being reset"));
 }
 var DEFAULT_BREAKER_CONFIG, browserCircuitBreaker;
 var init_browser_error_utils = __esm({