@lincoln504/pi-research 1.1.0 → 1.1.2

package/README.md

@@ -32,7 +32,7 @@ knowledge store on your machine.
 
 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 filesystem or shell access), and an evaluator decides whether
+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.
 
@@ -55,7 +55,7 @@ ask in natural language and the tool picks the right one:
 - **Free, unlimited search & 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 with no filesystem or shell access — safe to point at anything.
+- **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;
@@ -22178,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;
@@ -23255,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}`;
   }
@@ -23339,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)
 `);
@@ -23984,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({

package/docs/CHANGELOG.md

@@ -5,6 +5,32 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [1.1.2] - 2026-08-04
+
+> Supersedes `v1.1.1`, which was tagged but never published: its release run was
+> correctly blocked by a red CI, and the tag is retained only as a marker of that
+> attempt. Everything below is the full set of changes since 1.1.0.
+
+### Fixed
+- **The multi-process run-cap test counted cumulative slot acquisitions as concurrent ones.** The "thundering herd" test asserts the *concurrent* cap but tallied *cumulative* `acquired` events, and let its winners hold for a finite 4 s. On a slow runner the six contenders start staggered, so a late one can attempt after an early winner's hold has already elapsed, legitimately win the freed slot, and push the cumulative tally past the cap while at most `MAX` ever held at once — a false failure that blocked this release on Windows CI. Confirmed by direct reproduction: with the stagger forced, four acquisitions were recorded against a maximum of two concurrent holders, the late pair's acquire timestamps falling strictly after the early pair's releases on reused slots. Winners now hold until killed, so there is no free slot to win and the count measures genuine simultaneity — a strictly stronger assertion. Test-only; the semaphore itself was never at fault and is unchanged. (The sibling "distinct slot assignments" test was fixed the same way in 1.1.0; that change cited this test's own stated principle but left this test on the racy pattern.)
+- **Citation markers could be silently retargeted at the wrong source.** When merging researcher reports, `normalizeCitations` renumbers each report's local `[N]` markers to global ids — but a marker it could not map was left *verbatim* instead of being removed. Global ids are assigned densely from 1, so a surviving `[1]` no longer meant "this report's first source": it resolved against the renumbered global list and pointed at an unrelated document. Markers go unmapped whenever `parseCitations` legitimately drops an entry, e.g. a URL whose hostname has no dot (`localhost`, a bare internal host, a malformed line). This was not cosmetic — the normalized body is fed straight into the evaluator/synthesis prompt, which is explicitly told the numbering is already global, so the model faithfully reproduced the wrong attribution, and `ensureCitedLinks` then regenerated a `CITED LINKS` list perfectly consistent with it. A correct structure-preserving rewriter already existed on the synthesis path (added in 1.0.11); it is now shared, so dangling markers are removed cleanly while fenced blocks and inline-code spans — a quoted `items[12]` — stay untouched. The prior test could never have caught this: its assertion was structurally guaranteed by the CITED-LINKS slice regardless of marker handling.
+- **A retry could silently abandon the operation instead of retrying it.** `retryWithBackoff` awaited its inter-attempt sleep on an `unref`'d timer. The sleep *is* the operation — the retry has already been decided and the next attempt must run — and `abortableDelay`'s own docstring says exactly that (`web-scraper.ts` passes `keepAlive` with a comment explaining why); the backoff simply omitted it. The failure compounds itself: the transient network errors that trigger a retry are precisely the ones that leave no referenced socket handle, so the backoff is frequently the *only* pending handle, and Node drains the event loop and exits mid-retry. The next attempt never runs and nothing is reported — in the CLI neither branch of the top-level handler fires, so the user gets a bare exit with no report and no error. Affected every `retryWithBackoff` caller (LLM planning, all four security clients, YouTube transcripts) plus both knowledge-search retry loops.
+- **The circuit breaker could pin permanently in `HALF_OPEN`, collapsing parallel search bursts.** `onFailure` is the only path back to `OPEN` and is skipped for errors the breaker does not count, while `transitionTo('HALF_OPEN')` never re-arms `nextAttemptTime` — so a trial probe failing with a non-counted error left the breaker stuck with no time-based escape, fast-failing every caller beyond `halfOpenMaxCalls` (default 1) indefinitely. This was not a corner case for the browser pool: `DEFAULT_BREAKER_CONFIG.isTransientError` deliberately excludes pool-shutdown, draining, Cloudflare and task-timeout errors — exactly what a recovering or blocked pool returns — so the probe most likely to run was also the one most likely to pin it. A non-counted probe failure is now treated as *inconclusive* and re-opens with a fresh reset window.
+- **`npm install <dir>`, `file:`, `npm link` and `pi install <dir>` aborted during install.** The published package ships the built `skills/pi-research/scripts/run.mjs` and deliberately excludes its `run.ts` source, yet also ships `prepare.cjs` + `build.cjs` — and `prepare` runs `build.cjs all`, whose `skill` target hard-requires `run.ts` as its esbuild entry point. Running the shipped build against the shipped tree failed with `Could not resolve run.ts` and exit 1. Registry `.tgz` and `npx` installs were unaffected only because `prepare` does not run there. The target now no-ops when `run.ts` is absent and `run.mjs` is already built, and still errors when neither exists.
+- **A pool-reset error told callers to retry, but nothing recognised it.** `worker-pool-manager` throws `Worker pool is being reset, please retry` while auto-recovery swaps the pool, and no error classifier matched that string — so the first attempt rethrew instead of retrying. Auto-recovery fires only after 3 consecutive worker failures, i.e. exactly when a burst of tasks is in flight and would all fail together: the same user-visible shape as the leader-handover loss fixed in 1.1.0, entering through a different door. Now classified as a transient pool-unavailable condition.
+- **Cancelling a run at the wrong moment could kill the process.** `withTimeout`'s early-abort path returned before attaching to the caller-supplied promise, orphaning that promise's eventual rejection. Node 22+ defaults to `--unhandled-rejections=throw`, and the main process registers no `unhandledRejection` handler, so an Esc timed between two awaits (reachable via the YouTube transcript client, which threads the same signal into both) crashed the host instead of cancelling cleanly. The in-flight rejection is now adopted before bailing out.
+
+### Changed
+- **Model-resolution errors now lead with the credential path instead of pointing at `models.json`.** For a provider pi ships built in (openrouter, anthropic, openai, …), the fix for an unresolved model is a credential — after which pi fetches that provider's catalog, with real pricing and context limits, on its own. Both error messages instead named `~/.pi/agent/models.json` as the remedy, which is wrong for exactly that case and demonstrably led users to hand-write `models[]` entries. Because such an entry **replaces** pi's catalog entry wholesale rather than merging into it (`modelOverrides` is the merging mechanism), doing so silently zeroed out the model's pricing and capped its context and output windows. The messages now name `/login`, `auth.json` and the provider env var first, scope `models.json` to genuinely custom or self-hosted providers, and warn about the replace-vs-merge distinction.
+- **A cost of exactly `$0.00` is now shown rather than omitted.** Cost is computed locally as tokens × the model's price table, never read off the wire, so a model whose table is all zeros bills tokens and reports zero indefinitely. Every display site gated on `cost > 0`, which made a misconfigured price table indistinguishable from "nothing reported yet" — and on the CLI progress line a falsy cost suppressed the **token count** as well, so the run appeared to consume nothing. Zero is also the honest figure for flat-rate plans and local models. `recordLlmUsage` additionally warns once per model when tokens are billed against an all-zero table, naming the usual cause.
+- **Session Metrics now actually reports cost.** The view has always advertised "API cost estimates", but `SessionStats` carried no cost field to show; it now aggregates and displays one.
+
+### Documentation
+- **`README.md` claimed the research agent has "no filesystem or shell access" and is "safe to point at anything".** The shell half is accurate; the filesystem half was not — `read` and `grep` are registered unconditionally and the researcher exclusion list (`bash`, `write`, `edit`, `repl`, `git`, `terminal`) never excluded them. `ARCHITECTURE.md` documented this correctly, so the README was the outlier — and it is the sentence a user relies on when deciding whether to run this against a sensitive directory. Corrected to what the code actually enforces: no shell, no writes, but reads and searches within the working directory.
+- **The `knowledge-config` example was an unquoted shell pipe.** `... knowledge-config set none|project|global` sat inside a block `SKILL.md` explicitly instructs the agent to run on the user's behalf; pasted literally, bash executes `set none` and pipes into two "command not found" lines — so a user asking to *enable* the store would have it silently *disabled*. Now a `<none|project|global>` placeholder, fixed in all four copies.
+- **Exit-code documentation gaps.** `75` (at capacity) — 1.1.0's headline exit code — was missing from the CLI's own `--help`. And `78` from `knowledge` covers two very different conditions (store deliberately disabled vs. missing credentials) while `SKILL.md` documented only the first, telling agents to stay silent and continue on what is actually a hard configuration failure. Both surfaces now distinguish them.
+- **`docs/SDK.md` recommended a loader recipe that cannot work.** It suggested `node --experimental-transform-types your-script.ts` for consuming the TypeScript entrypoint; Node refuses to strip *or* transform TypeScript under `node_modules`, failing with `ERR_UNSUPPORTED_NODE_MODULES_TYPE_STRIPPING`. A loader (`tsx`/`ts-node`) or the pi host is mandatory, and the limitation is now stated.
+
 ## [1.1.0] - 2026-08-04
 
 ### Changed

package/docs/CONFIGURATION.md

@@ -218,7 +218,7 @@ set the knowledge-store mode per directory directly:
 
 ```sh
 pi-research knowledge-config                       # show the mode here and where it comes from
-pi-research knowledge-config set none|project|global
+pi-research knowledge-config set <none|project|global>   # pick ONE value
 ```
 
 Under the agent skill you don't have to run this yourself — you ask the agent (e.g. "disable the

package/docs/KNOWLEDGE-STORE.md

@@ -44,7 +44,7 @@ a project-scoped setting you can change per directory:
 | `none` | The store is disabled — nothing is read or written, the `research_knowledge_search` tool is not advertised to the agent, and `/knowledge-store` is unavailable. Re-enabling needs no restart (see [PI-EXTENSION.md](PI-EXTENSION.md) for the registration mechanics). |
 
 Change the mode for the current directory with the `/research-config` TUI (Knowledge Mode)
-in the pi extension, or with `pi-research knowledge-config set none|project|global` on the
+in the pi extension, or with `pi-research knowledge-config set <none|project|global>` (pick one value) on the
 standalone CLI. The setting persists to the per-directory project registry — see
 [CONFIGURATION.md](CONFIGURATION.md) for the full precedence chain. The change applies on
 the next run — no restart.

package/docs/SDK.md

@@ -33,13 +33,16 @@ global file entirely and run purely from defaults + `process.env` + `options.con
 > `enum` and constructor parameter properties, which Node's strip-only mode
 > (`--experimental-strip-types`, the default since Node 23.6) rejects with
 > `ERR_UNSUPPORTED_TYPESCRIPT_SYNTAX`. Use one of:
-> - the pi host, which loads it natively;
-> - **`node --experimental-transform-types your-script.ts`** — must be passed
->   explicitly; full transform is not the default on any current Node release;
+> - the pi host, which loads it natively (via `jiti`);
 > - a loader such as `tsx` or `ts-node`.
 >
-> Plain `node script.js` doing `require('@lincoln504/pi-research/sdk')`, or
-> `--experimental-strip-types`, will not work. (`engines.node` is `>=22.19.0`.)
+> **Bare Node cannot load it at all, with any flag.** Node refuses to strip or
+> transform TypeScript that lives under `node_modules` — as an installed
+> dependency's source does — failing with
+> `ERR_UNSUPPORTED_NODE_MODULES_TYPE_STRIPPING`. That applies to
+> `--experimental-transform-types` exactly as it does to
+> `--experimental-strip-types`, so neither flag helps here; a loader (or the pi
+> host) is mandatory. (`engines.node` is `>=22.19.0`.)
 
 ```typescript
 import {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@lincoln504/pi-research",
-  "version": "1.1.0",
+  "version": "1.1.2",
   "description": "A set of web research tools (search, scrape, and others) and research agent system that uses them safely and efficiently.",
   "type": "module",
   "private": false,

package/scripts/build.cjs

@@ -106,13 +106,31 @@ const TARGETS = {
     copyWebGpuProbe();
     copyPrompts();
   },
-  skill: () =>
-    esbuild.build({
+  skill: () => {
+    const entry = p('skills', 'pi-research', 'scripts', 'run.ts');
+    const outfile = p('skills', 'pi-research', 'scripts', 'run.mjs');
+    // The published package ships the BUILT run.mjs and deliberately excludes its
+    // run.ts source (package.json "files": "!skills/pi-research/scripts/run.ts"),
+    // yet it also ships prepare.cjs + build.cjs — and `prepare` runs `build.cjs all`.
+    // On any install that executes prepare against the shipped tree (npm install
+    // <dir>, file:, npm link, pi install <dir>) this target had no entry point and
+    // aborted the whole install with "Could not resolve run.ts". Registry .tgz and
+    // npx installs were unaffected only because prepare does not run there.
+    // Nothing to do when the artifact is already present and its source is not.
+    if (!fs.existsSync(entry)) {
+      if (fs.existsSync(outfile)) {
+        console.log('[build] skill: run.ts absent and run.mjs already built (published tree) — skipping');
+        return Promise.resolve();
+      }
+      throw new Error(`[build] skill: neither ${entry} nor a prebuilt ${outfile} exists`);
+    }
+    return esbuild.build({
       ...COMMON,
-      entryPoints: [p('skills', 'pi-research', 'scripts', 'run.ts')],
-      outfile: p('skills', 'pi-research', 'scripts', 'run.mjs'),
+      entryPoints: [entry],
+      outfile,
       banner: { js: SHEBANG },
-    }),
+    });
+  },
 };
 
 // The cli target's copyThreadWorker step depends on the worker output existing,

package/skills/pi-research/SKILL.md

@@ -2,7 +2,7 @@
 name: pi-research
 description: "Multi-agent web research for any coding agent. Use for anything requiring current information from the internet — news, trends, product/service/company facts, statistics, people, places, events, APIs, library behavior, or 'what is X / how does X work' questions. Also use to search a local knowledge store of previously researched findings before doing live research. Powered by the pi-research engine (search, stealth scraping, security databases, Stack Exchange). Not for reading local files, running project commands, or analyzing this repository's own source."
 license: MIT
-metadata: { "author": "Lincoln Deen", "version": "1.1.0", "package": "@lincoln504/pi-research", "engine": "pi-research-sdk", "openclaw": { "requires": { "bins": ["node"] } } }
+metadata: { "author": "Lincoln Deen", "version": "1.1.2", "package": "@lincoln504/pi-research", "engine": "pi-research-sdk", "openclaw": { "requires": { "bins": ["node"] } } }
 allowed-tools: Bash(node:*)
 ---
 
@@ -63,7 +63,7 @@ node "<SKILL_DIR>/scripts/run.mjs" status    [--json]
 | Exit | Meaning | Action |
 |------|---------|--------|
 | `0` | Success | Read stdout; cite sources; relay any "saved to: <path>" line. |
-| `78` on `knowledge` | Store disabled/unconfigured | Silent; proceed to `research`. |
+| `78` on `knowledge` | Two cases — **read stderr to tell them apart.** | Says the store is **disabled**: silent; proceed to `research`. Mentions **credentials/model/API key**: this is the same hard config failure as `78` on `research` — **stop and relay full stderr**; don't silently continue, `research` will fail the same way. |
 | `78` on `research` | Engine missing or no model/key | **Stop. Relay full stderr** (it shows where to configure). Don't retry until fixed. |
 | `75` | Machine at capacity — other research runs are already using every slot | **Nothing is broken.** Wait for an in-flight run to finish, then retry this query once. Don't reconfigure anything and don't retry in a tight loop. |
 | `70` | Runtime error | Relay stderr; suggest one retry for transient failures (network, rate limit). |
@@ -81,7 +81,7 @@ the new setting. Check the current one first if useful:
 
 ```
 node "<SKILL_DIR>/scripts/run.mjs" knowledge-config                    # current mode + where it's set
-node "<SKILL_DIR>/scripts/run.mjs" knowledge-config set none|project|global
+node "<SKILL_DIR>/scripts/run.mjs" knowledge-config set <none|project|global>   # pick ONE value
 ```
 
 The change applies to the current directory on the next run. Never change it unprompted.

package/skills/pi-research/references/configuration.md

@@ -52,7 +52,7 @@ shared store — the default), `project` (scoped to the current directory), or `
 
 ```sh
 node "<SKILL_DIR>/scripts/run.mjs" knowledge-config                     # current mode + its source
-node "<SKILL_DIR>/scripts/run.mjs" knowledge-config set none|project|global
+node "<SKILL_DIR>/scripts/run.mjs" knowledge-config set <none|project|global>   # pick ONE value
 ```
 
 `set` persists to the per-directory project registry (`~/.pi/research/state/

package/src/cli.ts

@@ -137,9 +137,19 @@ function makeProgressObserver(): HeadlessObserverOptions {
         case 'evaluation_decision':
           toStderr(`  • evaluator: ${data?.action}\n`);
           break;
-        case 'tokens_consumed':
-          if (data?.cost) toStderr(`  • tokens: ${data?.tokens ?? 0} ($${Number(data.cost).toFixed(4)})\n`);
+        case 'tokens_consumed': {
+          // A truthiness check on cost used to gate this whole line, so a model with
+          // an all-zero price table suppressed the TOKEN count as well — the run
+          // looked like it consumed nothing. Tokens stand on their own; cost is
+          // appended whenever it is a number, including 0.
+          const consumed = Number(data?.tokens ?? 0);
+          const costVal = typeof data?.cost === 'number' ? data.cost : undefined;
+          if (consumed > 0 || costVal !== undefined) {
+            const costPart = costVal === undefined ? '' : ` ($${costVal.toFixed(4)})`;
+            toStderr(`  • tokens: ${consumed}${costPart}\n`);
+          }
           break;
+        }
         case 'complete':
           toStderr(`  • complete (${data?.result?.length ?? 0} chars)\n`);
           break;
@@ -1016,7 +1026,9 @@ CONFIGURE
 EXIT CODES
   0  success
   64 bad arguments
+  75 at capacity — every concurrent run slot is busy; nothing is broken, retry later
   78 not configured — message prints the exact locations to fix
+     (on \`knowledge\`, also returned when the store is deliberately disabled)
   70 runtime error (network, provider, internal)
 `;
 }

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

@@ -219,6 +219,13 @@ export function constructMinimalModel(provider: string, modelId: string, _apiKey
     baseUrl: '', // 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: 128_000,
     maxTokens: 32_768,
@@ -253,7 +260,7 @@ export function resolveModel(registry: ModelRegistry, modelSpec?: string, provid
         return constructMinimalModel(prov, modelId, apiKey);
       }
       
-      throw new Error(`Model "${modelSpec}" not found in pi's configured model registry. Check ${path.join(getAgentDir(), 'models.json')}.`);
+      throw new Error(buildModelNotFoundMessage(modelSpec));
     }
     
     // Validate format: must contain a slash OR be found as a bare model ID.
@@ -306,11 +313,41 @@ export function resolveModel(registry: ModelRegistry, modelSpec?: string, provid
     return constructMinimalModel(provider, modelSpec, apiKey);
   }
 
-  throw new Error(
-    `No LLM model available. Please configure your model registry (${path.join(getAgentDir(), 'models.json')}) or provide an explicit apiKey.`,
+  throw new Error(buildNoModelAvailableMessage());
+}
+
+/**
+ * Credential-first guidance for model-resolution failures.
+ *
+ * These messages used to say only "Check ~/.pi/agent/models.json", which is the
+ * WRONG remedy for a provider pi ships built in: the fix there is a credential,
+ * after which pi fetches the provider's catalog (with real pricing and context
+ * limits) on its own. Following the old advice, users hand-wrote `models[]`
+ * entries — and because such an entry REPLACES pi's catalog entry wholesale
+ * rather than merging into it, that silently zeroed out pricing and capped
+ * context/output windows. Lead with the credential path; scope models.json to
+ * genuinely custom providers; name `modelOverrides` for single-field tweaks.
+ */
+function credentialGuidance(): string {
+  const agentDir = getAgentDir();
+  return (
+    `  • Provider pi supports built-in (openrouter, anthropic, openai, …): add a credential — run \`pi\` and use /login, ` +
+    `set the provider's API-key environment variable, or add it to ${path.join(agentDir, 'auth.json')}. ` +
+    `pi then fetches that provider's model catalog automatically.\n` +
+    `  • Custom or self-hosted provider (Ollama, vLLM, a proxy): declare it in ${path.join(agentDir, 'models.json')}.\n` +
+    `    Note: a models.json entry REPLACES pi's catalog entry for the same model id, discarding its pricing and\n` +
+    `    context/output limits. To adjust a single field of a built-in model, use "modelOverrides" instead — it merges.`
   );
 }
 
+export function buildModelNotFoundMessage(modelSpec: string): string {
+  return `Model "${modelSpec}" not found in pi's model registry.\n${credentialGuidance()}`;
+}
+
+export function buildNoModelAvailableMessage(): string {
+  return `No LLM model available.\n${credentialGuidance()}\n  • Or pass an explicit apiKey.`;
+}
+
 /**
  * Read the user's provider order from ~/.pi/agent/models.json.
  * Returns provider keys in document (insertion) order, or [] when the file is

package/src/core/llm/research-model-resolver.ts

@@ -9,7 +9,7 @@ import { type Model } from '@earendil-works/pi-ai';
 import { type ModelRegistry } from '@earendil-works/pi-coding-agent';
 import { getConfig } from '../../config.ts';
 import { logger } from '../../logger.ts';
-import { pickPreferredAvailable, readModelsJsonProviderOrder, safeGetAll, safeGetAvailable } from './model-registry-factory.ts';
+import { buildNoModelAvailableMessage, pickPreferredAvailable, readModelsJsonProviderOrder, safeGetAll, safeGetAvailable } from './model-registry-factory.ts';
 
 /**
  * Resolve the research model with standardized priority:
@@ -87,5 +87,5 @@ export function resolveResearchModel(options: {
     return pickPreferredAvailable(anyModel, readModelsJsonProviderOrder()) as Model<any>;
   }
 
-  throw new Error('No LLM model available for research. Please configure your model registry (~/.pi/agent/models.json).');
+  throw new Error(buildNoModelAvailableMessage());
 }

package/src/infrastructure/browser/browser-error-utils.ts

@@ -109,7 +109,13 @@ export function isPoolShutdownError(error: unknown): boolean {
     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')
+        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')
     );
 }
 

package/src/infrastructure/browser/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({

package/src/orchestration/research-synthesis-service.ts

@@ -10,7 +10,7 @@
  */
 
 import { parseCitations } from '../utils/text-utils.ts';
-import { normalizeCitations, formatCitedLinks, type GlobalCitation } from '../utils/citation-utils.ts';
+import { normalizeCitations, formatCitedLinks, rewriteCitationMarkers, type GlobalCitation } from '../utils/citation-utils.ts';
 import { lastCitedLinksHeaderIndex } from '../utils/text-utils.ts';
 import { getScrapedLinks, isTranscribedLink, normalizeUrl } from '../utils/shared-links.ts';
 import { stripTrailingLlmPunctuation } from '../utils/url-utils.ts';
@@ -33,86 +33,6 @@ const NO_SOURCES_NOTE =
 const 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 — check each one before relying on it._';
 
-/**
- * Largest `[N]` treated as a citation marker. Inline markers index a source list
- * that is realistically well under this; the bound exists so an ordinary bracketed
- * number in prose — a year (`[2023]`), an issue id, an array index — is left alone
- * instead of being silently deleted as a "dangling citation".
- */
-const MAX_PLAUSIBLE_CITATION_MARKER = 200;
-
-/**
- * Rewrite inline `[N]` citation markers in a prose body: renumber the ones we can
- * map, delete the ones known to dangle, leave everything else untouched.
- *
- * Deletion is whitespace-aware rather than followed by a global space collapse.
- * A blanket `text.replace(/  +/g, ' ')` also eats *leading* indentation, which
- * silently flattens nested list levels into one and turns 4-space indented code
- * blocks into paragraphs — corrupting the structure of every report that contains
- * them. So the pad preceding a deleted marker is consumed only when the marker is
- * mid-line (i.e. real prose spacing); line-leading indentation is preserved.
- *
- * Code is skipped entirely. A report may quote code containing bracketed integers
- * (`items[12]`), and on the no-CITED-LINKS path *every* out-of-range marker is treated
- * as dangling — so without this guard a quoted array index would be silently deleted
- * from the user's code sample. Fenced blocks are tracked across lines; single-backtick
- * spans are detected by an odd backtick count earlier on the same line.
- *
- * @param remap  local marker number → verified global id
- * @param isDangling  whether a marker not present in `remap` should be deleted
- */
-function rewriteCitationMarkers(
-  text: string,
-  remap: Map<number, number>,
-  isDangling: (n: number) => boolean,
-): string {
-  const inFence = fencedCodeMask(text);
-  return text.replace(/([ \t]*)\[(\d+)\]/g, (match, pad: string, digits: string, offset: number) => {
-    const n = parseInt(digits, 10);
-    const mapped = remap.get(n);
-    if (mapped !== undefined) return `${pad}[${mapped}]`;
-    // Citation numbering is 1-based; `[0]` is always an index or a literal, never a marker.
-    if (n < 1 || n > MAX_PLAUSIBLE_CITATION_MARKER || !isDangling(n)) return match;
-    if (inFence(offset) || inInlineCodeSpan(text, offset)) return match;
-    // Preserve indentation when nothing but whitespace precedes on this line;
-    // otherwise drop the pad too so no double space is left behind.
-    const lineStart = text.lastIndexOf('\n', offset - 1) + 1;
-    return text.slice(lineStart, offset).trim() === '' ? pad : '';
-  });
-}
-
-/**
- * Build an `offset → is inside a ``` fenced block` predicate for `text`.
- *
- * Computed once per rewrite (a single line scan) rather than per marker, so marker
- * rewriting stays linear in the body length.
- */
-function fencedCodeMask(text: string): (offset: number) => boolean {
-  const ranges: Array<[number, number]> = [];
-  let open = -1;
-  let pos = 0;
-  for (const line of text.split('\n')) {
-    if (/^\s{0,3}(```|~~~)/.test(line)) {
-      if (open < 0) open = pos;
-      else {
-        ranges.push([open, pos + line.length]);
-        open = -1;
-      }
-    }
-    pos += line.length + 1; // +1 for the '\n' consumed by split
-  }
-  // An unterminated fence runs to the end of the body — treat the remainder as code.
-  if (open >= 0) ranges.push([open, text.length]);
-  return (offset: number) => ranges.some(([start, end]) => offset >= start && offset < end);
-}
-
-/** Whether `offset` sits inside a single-backtick code span on its own line. */
-function inInlineCodeSpan(text: string, offset: number): boolean {
-  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;
-}
 
 /**
  * Redact inline `https?://` tokens in synthesis prose whose URL was NOT retrieved

package/src/tools/research-knowledge-search.ts

@@ -481,7 +481,10 @@ export async function runBackgroundExtraction(
       const delay = 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 (${msg}); retrying in ${delay}ms`);
-      await abortableDelay(delay, signal);
+      // keepAlive=true: the retry is already committed and the next attempt must
+      // run, so this sleep is foreground work. An unref'd timer here can be the
+      // only pending handle and let the process exit mid-retry (see abortableDelay).
+      await abortableDelay(delay, signal, true);
     }
   }
 
@@ -625,7 +628,10 @@ export async function triageRelevantUrls(
       const delay = 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 (${msg}); retrying in ${delay}ms`);
-      await abortableDelay(delay, signal);
+      // keepAlive=true: the retry is already committed and the next attempt must
+      // run, so this sleep is foreground work. An unref'd timer here can be the
+      // only pending handle and let the process exit mid-retry (see abortableDelay).
+      await abortableDelay(delay, signal, true);
     }
   }
 

package/src/utils/circuit-breaker.ts

@@ -78,6 +78,26 @@ export class CircuitBreaker {
       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') {
+        // The trial probe failed for a reason this breaker does not count. That is
+        // INCONCLUSIVE, not healthy — so re-open and wait out another reset window
+        // rather than staying HALF_OPEN.
+        //
+        // Without this the breaker pins permanently: onFailure is the only path to
+        // OPEN, and it is skipped for non-counted errors, while transitionTo(HALF_OPEN)
+        // never re-arms nextAttemptTime. The admission gate above then fast-fails every
+        // caller beyond halfOpenMaxCalls (default 1) forever. This is not a corner case
+        // for the browser pool: DEFAULT_BREAKER_CONFIG.isTransientError deliberately
+        // excludes pool-shutdown, draining, Cloudflare and task-timeout errors — exactly
+        // what a recovering or blocked pool returns — so the probe most likely to run is
+        // also the one most likely to pin the breaker. Observed effect: 19 of a 20-query
+        // parallel burst fast-failing instantly, surfacing to the researcher as
+        // "your query may be too narrow".
+        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 {

package/src/utils/citation-utils.ts

@@ -67,13 +67,28 @@ export function normalizeCitations(reports: Map<string, string>): {
     const headerIdx = lastCitedLinksHeaderIndex(report);
     let content = headerIdx >= 0 ? report.slice(0, headerIdx) : report;
 
-    // Replace [N] with [GlobalID]
-    // Also handle [N][M] combinations
-    content = content.replace(/\[(\d+)\]/g, (match, p1) => {
-      const localId = parseInt(p1, 10);
-      const globalId = localToGlobal.get(localId);
-      return globalId !== undefined ? `[${globalId}]` : match;
-    });
+    // Renumber local [N] markers to their global ids, and DELETE the ones that could
+    // not be mapped.
+    //
+    // Leaving an unmapped marker in place (the previous `return match`) was a silent
+    // misattribution bug, not a harmless no-op: global ids are assigned densely from 1,
+    // so a surviving `[1]` no longer means "this report's first source" — it resolves
+    // against the renumbered global list and points at a completely different document.
+    // Markers go unmapped whenever parseCitations dropped the entry (e.g. a URL whose
+    // hostname has no dot: `localhost`, a bare internal host, a malformed line). The
+    // result is fed straight into the evaluator/synthesis prompt, which is explicitly
+    // told the numbering is already normalized — so the model faithfully reproduces the
+    // wrong attribution, and ensureCitedLinks then regenerates a CITED LINKS list that
+    // looks perfectly consistent with it.
+    //
+    // rewriteCitationMarkers is the same routine the synthesis path already uses: it
+    // skips fenced blocks and inline code spans (so a quoted `items[12]` survives),
+    // bounds what counts as a marker, and preserves line-leading indentation.
+    content = rewriteCitationMarkers(
+      content,
+      localToGlobal,
+      (n) => !localToGlobal.has(n),
+    );
 
     normalizedReports.set(id, content.trim());
   }
@@ -95,3 +110,84 @@ export function formatCitedLinks(citations: GlobalCitation[]): string {
 
   return `CITED LINKS\n${links.join('\n')}`;
 }
+
+/**
+ * Largest `[N]` treated as a citation marker. Inline markers index a source list
+ * that is realistically well under this; the bound exists so an ordinary bracketed
+ * number in prose — a year (`[2023]`), an issue id, an array index — is left alone
+ * instead of being silently deleted as a "dangling citation".
+ */
+export const MAX_PLAUSIBLE_CITATION_MARKER = 200;
+
+/**
+ * Rewrite inline `[N]` citation markers in a prose body: renumber the ones we can
+ * map, delete the ones known to dangle, leave everything else untouched.
+ *
+ * Deletion is whitespace-aware rather than followed by a global space collapse.
+ * A blanket `text.replace(/  +/g, ' ')` also eats *leading* indentation, which
+ * silently flattens nested list levels into one and turns 4-space indented code
+ * blocks into paragraphs — corrupting the structure of every report that contains
+ * them. So the pad preceding a deleted marker is consumed only when the marker is
+ * mid-line (i.e. real prose spacing); line-leading indentation is preserved.
+ *
+ * Code is skipped entirely. A report may quote code containing bracketed integers
+ * (`items[12]`), and on the no-CITED-LINKS path *every* out-of-range marker is treated
+ * as dangling — so without this guard a quoted array index would be silently deleted
+ * from the user's code sample. Fenced blocks are tracked across lines; single-backtick
+ * spans are detected by an odd backtick count earlier on the same line.
+ *
+ * @param remap  local marker number → verified global id
+ * @param isDangling  whether a marker not present in `remap` should be deleted
+ */
+export function rewriteCitationMarkers(
+  text: string,
+  remap: Map<number, number>,
+  isDangling: (n: number) => boolean,
+): string {
+  const inFence = fencedCodeMask(text);
+  return text.replace(/([ \t]*)\[(\d+)\]/g, (match, pad: string, digits: string, offset: number) => {
+    const n = parseInt(digits, 10);
+    const mapped = remap.get(n);
+    if (mapped !== undefined) return `${pad}[${mapped}]`;
+    // Citation numbering is 1-based; `[0]` is always an index or a literal, never a marker.
+    if (n < 1 || n > MAX_PLAUSIBLE_CITATION_MARKER || !isDangling(n)) return match;
+    if (inFence(offset) || inInlineCodeSpan(text, offset)) return match;
+    // Preserve indentation when nothing but whitespace precedes on this line;
+    // otherwise drop the pad too so no double space is left behind.
+    const lineStart = text.lastIndexOf('\n', offset - 1) + 1;
+    return text.slice(lineStart, offset).trim() === '' ? pad : '';
+  });
+}
+
+/**
+ * Build an `offset → is inside a ``` fenced block` predicate for `text`.
+ *
+ * Computed once per rewrite (a single line scan) rather than per marker, so marker
+ * rewriting stays linear in the body length.
+ */
+function fencedCodeMask(text: string): (offset: number) => boolean {
+  const ranges: Array<[number, number]> = [];
+  let open = -1;
+  let pos = 0;
+  for (const line of text.split('\n')) {
+    if (/^\s{0,3}(```|~~~)/.test(line)) {
+      if (open < 0) open = pos;
+      else {
+        ranges.push([open, pos + line.length]);
+        open = -1;
+      }
+    }
+    pos += line.length + 1; // +1 for the '\n' consumed by split
+  }
+  // An unterminated fence runs to the end of the body — treat the remainder as code.
+  if (open >= 0) ranges.push([open, text.length]);
+  return (offset: number) => ranges.some(([start, end]) => offset >= start && offset < end);
+}
+
+/** Whether `offset` sits inside a single-backtick code span on its own line. */
+function inInlineCodeSpan(text: string, offset: number): boolean {
+  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;
+}

package/src/utils/llm-usage.ts

@@ -13,8 +13,44 @@
 
 import type { Model } from '@earendil-works/pi-ai';
 import { extractUsage } from '../types/llm.ts';
+import { logger } from '../logger.ts';
 import { metrics } from './metrics.ts';
 
+/** Models already warned about, so the notice fires at most once per model per process. */
+const unpricedModelsWarned = new Set<string>();
+
+/**
+ * Warn once when a model bills tokens but carries an all-zero price table.
+ *
+ * Cost is never read off the wire — pi computes it as tokens × the model's local
+ * price table — so an unpriced table yields $0.00 silently and indefinitely. That
+ * is legitimate for flat-rate plans and local servers, but it is also exactly what
+ * a misconfiguration looks like: a hand-written `models[]` entry in models.json
+ * REPLACES pi's catalog entry for the same id, discarding its pricing. This
+ * happened in practice and went unnoticed for weeks because every display site
+ * suppressed a zero cost. The message deliberately does not assert a fault — it
+ * states the condition and names the usual cause.
+ */
+function warnIfUnpriced(model: Model<any>, tokens: number, cost: number): void {
+  if (tokens <= 0 || cost > 0) return;
+  const m = model as unknown as { provider?: string; id?: string; cost?: Record<string, number> };
+  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 — 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 — remove it and let pi's catalog supply the model, or use "modelOverrides", which merges.`
+  );
+}
+
 /** Structural subset of the run observer — just the token sink. Kept structural (rather
  *  than importing ResearchObserver from core/) so this foundation-layer helper does not
  *  depend on an upper layer; the full ResearchObserver satisfies it. */
@@ -43,6 +79,7 @@ export function recordLlmUsage(
 ): { tokens: number; cost: number } {
   if (!rawUsage) return { tokens: 0, cost: 0 };
   const { tokens, cost } = extractUsage(model, rawUsage);
+  warnIfUnpriced(model, tokens, cost);
   if (tokens > 0 || cost > 0) {
     const labels: Record<string, string> = { component: opts.component };
     if (opts.complexity !== undefined) labels['complexity'] = String(opts.complexity);

package/src/utils/metrics-summary.ts

@@ -283,8 +283,15 @@ export function buildResearchSummary(stats: ResearchStats): string {
   if (stats.tokens > 0) {
     resourceParts.push(`**${formatTokens(stats.tokens)}** tokens`);
   }
-  if (stats.cost > 0) {
-    const costStr = stats.cost < 0.01 ? '<$0.01' : `$${stats.cost.toFixed(2)}`;
+  // Render the cost whenever tokens were actually billed-through, INCLUDING when it
+  // is exactly zero. Gating on `cost > 0` hid a real defect for weeks: a model whose
+  // price table is all zeros (an unpriced or catalog-overwritten entry) produced no
+  // cost line at all, so a misconfiguration was indistinguishable from a run that
+  // simply had not reported yet. "$0.00" beside a large token count is conspicuous;
+  // silence is not. Zero is also the honest figure for flat-rate and local providers.
+  if (stats.tokens > 0 || stats.cost > 0) {
+    const costStr =
+      stats.cost === 0 ? '$0.00' : stats.cost < 0.01 ? '<$0.01' : `$${stats.cost.toFixed(2)}`;
     resourceParts.push(`**${costStr}**`);
   }
   if (stats.durationMs > 0) {
@@ -317,6 +324,9 @@ export interface SessionStats {
   totalUrlsDiscovered: number;
   totalSearchQueries: number;
   totalTokens: number;
+  /** Summed LLM cost across the session's runs. The Session Metrics UI advertises
+   *  "API cost estimates"; without this field it had no cost to show. */
+  totalCost: number;
   totalToolUsage: {
     searches: number;
     scrapes: number;
@@ -339,6 +349,7 @@ export function aggregateSessionStats(
   let totalUrlsDiscovered = 0;
   let totalSearchQueries = 0;
   let totalTokens = 0;
+  let totalCost = 0;
   const totalToolUsage = {
     searches: 0,
     scrapes: 0,
@@ -359,6 +370,7 @@ export function aggregateSessionStats(
       totalUrlsDiscovered += stats.urlsDiscovered;
       totalSearchQueries += stats.searchQueries;
       totalTokens += stats.tokens;
+      totalCost += stats.cost;
       totalToolUsage.searches += stats.toolUsage.searches;
       totalToolUsage.scrapes += stats.toolUsage.scrapes;
       totalToolUsage.securitySearches += stats.toolUsage.securitySearches;
@@ -377,6 +389,7 @@ export function aggregateSessionStats(
     totalUrlsDiscovered,
     totalSearchQueries,
     totalTokens,
+    totalCost,
     totalToolUsage,
   };
 }
@@ -403,6 +416,16 @@ export function buildSessionOverview(stats: SessionStats): string {
   }
   if (stats.totalTokens > 0) {
     overviewParts.push(`**${formatTokens(stats.totalTokens)}** tokens`);
+    // Shown alongside tokens even at exactly $0.00 — the Session Metrics view
+    // advertises cost estimates, and a silent omission is what let an unpriced
+    // model table go unnoticed. Zero is correct for flat-rate and local providers.
+    const costStr =
+      stats.totalCost === 0
+        ? '$0.00'
+        : stats.totalCost < 0.01
+          ? '<$0.01'
+          : `$${stats.totalCost.toFixed(2)}`;
+    overviewParts.push(`**${costStr}**`);
   }
   if (stats.totalDurationMs > 0) {
     overviewParts.push(`**${formatDuration(stats.totalDurationMs)}** total research time`);

package/src/utils/research-export.ts

@@ -207,8 +207,15 @@ export async function exportResearchReport(
  */
 export function appendExportMessage(result: string, filepath: string, totalCost?: number): string {
   let footer = `\n\n---\n\nResearch report saved to: ${filepath}`;
-  if (totalCost !== undefined && totalCost > 0) {
-    const costStr = totalCost < 0.01 ? '<$0.01' : `$${totalCost.toFixed(4)}`.replace(/0+$/, '').replace(/\.$/, '');
+  // Report a defined cost even when it is exactly zero — suppressing it made an
+  // unpriced/misconfigured model table look identical to "no cost reported yet".
+  if (totalCost !== undefined) {
+    const costStr =
+      totalCost === 0
+        ? '$0.00'
+        : totalCost < 0.01
+          ? '<$0.01'
+          : `$${totalCost.toFixed(4)}`.replace(/0+$/, '').replace(/\.$/, '');
     footer += `\nTotal cost: ${costStr}`;
   }
   return result + footer;

package/src/web-research/retry-utils.ts

@@ -141,6 +141,11 @@ export function withTimeout<T>(
     // aborted before we start means an external (user) cancellation, not a timeout —
     // a clean stop, so log at debug, not error.
     if (combinedSignal.aborted) {
+      // `promise` is a parameter, so the caller already started it. Returning here
+      // skips the promise.then(...) attachment below, leaving its eventual rejection
+      // with no handler — and Node 22 defaults to --unhandled-rejections=throw, so
+      // that kills the process. Adopt the rejection before bailing out.
+      void promise.catch(() => undefined);
       logger.debug(`[withTimeout] ${label} already aborted at start (external cancellation)`);
       return reject(new Error(`${label} cancelled or timed out`));
     }
@@ -319,7 +324,14 @@ export async function retryWithBackoff<T>(
       // the full backoff. If the wait is aborted, surface the original transient
       // error (not the synthetic AbortError) so callers see the real cause.
       try {
-        await abortableDelay(delay, opts.signal);
+        // keepAlive=true: this sleep IS the operation. The retry has already been
+        // decided and the next attempt must run, so the timer must hold the event
+        // loop open. Without it, a transient network failure — which by its nature
+        // leaves no referenced socket handle — can make the backoff the sole pending
+        // handle, and Node drains the loop and exits mid-retry. The attempt never
+        // runs, and no error surfaces: in the CLI neither branch of the top-level
+        // handler fires, so the user gets a bare exit with no report.
+        await abortableDelay(delay, opts.signal, true);
       } catch {
         metrics.increment('retry_aborted_total', 1, { label: opts.label });
         throw lastError;