@lincoln504/pi-research 1.1.0 → 1.2.0

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);
     }
   }
 
@@ -956,6 +962,21 @@ export function createResearchKnowledgeSearchTool(iface?: ConfigInterface): Tool
         return buildSteeringResult(result, urls);
       } catch (error) {
         const durationMs = Date.now() - startTime;
+        const msg = error instanceof Error ? error.message : String(error);
+
+        // A CANCELLED search is not an empty store. Reporting the miss string here
+        // told the calling agent, definitively, that the knowledge store has
+        // nothing on this topic — so it would go straight to full live research,
+        // the very work the user just interrupted. Propagate the abort instead;
+        // the run is ending either way. (Same misclassification as the search
+        // layer's "browser workers may be unavailable" on Ctrl-C.)
+        if (signal?.aborted || (error instanceof Error && error.name === 'AbortError') || /^(aborted|research (aborted|cancelled))$/i.test(msg)) {
+          metrics.observe('research_knowledge_search_duration_ms', durationMs, { status: 'cancelled' });
+          metrics.increment('research_knowledge_search_total', 1, { status: 'cancelled' });
+          logger.debug('[research-knowledge-search] Cancelled mid-search — propagating rather than reporting an empty store.');
+          throw error;
+        }
+
         metrics.observe('research_knowledge_search_duration_ms', durationMs, { status: 'error' });
         metrics.increment('research_knowledge_search_total', 1, { status: 'error' });
 

package/src/tools/search.ts

@@ -106,7 +106,12 @@ export function createSearchTool(options: {
         results.forEach((r, i) => {
           markdown += `## Query ${i + 1}: ${r.query}\n`;
           if (r.results.length === 0) {
-            markdown += `*No results found.*\n\n`;
+            // Render the attributed failure, not a bare "no results": a timeout or
+            // dead worker says nothing about the query, and presenting it as an
+            // empty result sent the model off rewriting perfectly good queries —
+            // the misdirection QueryFailure exists to prevent. This is the only
+            // surface the researcher agent actually reads.
+            markdown += r.error ? `*${r.error.message}*\n\n` : `*No results found.*\n\n`;
           } else {
             r.results.forEach((item, j) => {
               markdown += `[${j + 1}] **${item.title}**\n${item.url}\n${item.content}\n\n`;

package/src/utils/atomic-replace.ts

@@ -0,0 +1,101 @@
+/**
+ * Atomic file replacement, with the Windows caveat handled honestly.
+ *
+ * The temp-file + fsync + rename dance exists so a reader never observes a partial
+ * file and a crash never leaves one: rename is atomic, so the destination is either
+ * entirely the old content or entirely the new.
+ *
+ * On Windows that guarantee is easy to lose. The long-standing comment at these call
+ * sites — "fs.rename fails on Windows if target exists (NTFS)" — is not true: Node
+ * calls `MoveFileExW` with `MOVEFILE_REPLACE_EXISTING`, so replacing an existing file
+ * is fine. What actually fails is a rename whose TARGET is held open by another
+ * process without delete sharing (an AV scanner mid-scan, a backup agent), which
+ * surfaces as EPERM/EBUSY/EACCES.
+ *
+ * The old remedy — fall straight to `copyFile` — traded a transient, retryable error
+ * for a permanent hazard: `copyFile` truncates the destination and rewrites it in
+ * place, so a concurrent reader or a crash mid-copy sees a torn or zero-length file.
+ * For `state.json` (leader election, server auth secrets) and `config.env` (API keys)
+ * that is a much worse outcome than the error it was avoiding.
+ *
+ * So: retry the rename first. An AV lock clears in tens of milliseconds, and a retried
+ * rename stays atomic. Only a lock that outlives every retry falls back to copying,
+ * which is reported to the caller so it can be logged as the degraded path it is.
+ */
+
+import * as fs from 'node:fs/promises';
+import * as fsSync from 'node:fs';
+
+/** Transient Windows sharing/locking failures — worth retrying, unlike ENOENT/ENOSPC. */
+const RETRYABLE_CODES = new Set(['EPERM', 'EBUSY', 'EACCES']);
+
+const MAX_RENAME_ATTEMPTS = 5;
+const RENAME_RETRY_DELAY_MS = 25;
+
+export type ReplaceOutcome = 'renamed' | 'copied';
+
+function isRetryable(err: unknown): boolean {
+  const code = (err as NodeJS.ErrnoException | undefined)?.code;
+  return code !== undefined && RETRYABLE_CODES.has(code);
+}
+
+/**
+ * Replace `destPath` with `tmpPath` atomically where the platform allows it.
+ *
+ * Returns `'renamed'` for the atomic path and `'copied'` for the degraded Windows
+ * fallback. Rethrows on every non-Windows failure, and on Windows failures that are
+ * not lock-related.
+ */
+export async function replaceFile(tmpPath: string, destPath: string): Promise<ReplaceOutcome> {
+  let lastError: unknown;
+  for (let attempt = 0; attempt < MAX_RENAME_ATTEMPTS; attempt++) {
+    try {
+      await fs.rename(tmpPath, destPath);
+      return 'renamed';
+    } catch (err) {
+      lastError = err;
+      // Only a Windows sharing conflict is worth another try; anything else (and any
+      // failure on a POSIX platform, where rename-over-existing always works) is real.
+      if (process.platform !== 'win32' || !isRetryable(err)) throw err;
+      if (attempt < MAX_RENAME_ATTEMPTS - 1) {
+        await new Promise((r) => setTimeout(r, RENAME_RETRY_DELAY_MS * (attempt + 1)));
+      }
+    }
+  }
+
+  // Every retry lost to the same lock. Copying is not atomic — a reader can catch the
+  // destination mid-write — but it is the only remaining way to persist the data.
+  try {
+    await fs.copyFile(tmpPath, destPath);
+    return 'copied';
+  } catch {
+    throw lastError;
+  }
+}
+
+/** Synchronous {@link replaceFile}, for the config writer, which is sync throughout. */
+export function replaceFileSync(tmpPath: string, destPath: string): ReplaceOutcome {
+  let lastError: unknown;
+  for (let attempt = 0; attempt < MAX_RENAME_ATTEMPTS; attempt++) {
+    try {
+      fsSync.renameSync(tmpPath, destPath);
+      return 'renamed';
+    } catch (err) {
+      lastError = err;
+      if (process.platform !== 'win32' || !isRetryable(err)) throw err;
+      if (attempt < MAX_RENAME_ATTEMPTS - 1) {
+        // Sync busy-wait: this path is rare, bounded (~250ms worst case) and the
+        // caller is already blocking on a synchronous write.
+        const until = Date.now() + RENAME_RETRY_DELAY_MS * (attempt + 1);
+        while (Date.now() < until) { /* spin */ }
+      }
+    }
+  }
+
+  try {
+    fsSync.copyFileSync(tmpPath, destPath);
+    return 'copied';
+  } catch {
+    throw lastError;
+  }
+}

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

@@ -16,7 +16,9 @@ export interface GlobalCitation extends Citation {
  * @param reports - Map of researcher ID to report content
  * @returns Object containing normalized reports and the global citation list
  */
-export function normalizeCitations(reports: Map<string, string>): {
+// ReadonlyMap: this only reads `reports` (it returns a NEW normalizedReports map),
+// and callers now pass a read-only view to avoid create-on-read side effects.
+export function normalizeCitations(reports: ReadonlyMap<string, string>): {
   normalizedReports: Map<string, string>;
   globalCitations: GlobalCitation[];
 } {
@@ -67,13 +69,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 +112,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/http-body.ts

@@ -0,0 +1,176 @@
+/**
+ * Capped response-body reading.
+ *
+ * `response.json()` and `response.text()` buffer the WHOLE body into the main
+ * process before anything can inspect its size — the byte count is only knowable
+ * after the memory has already been committed. A hostile or merely broken upstream
+ * can therefore drive this process to an OOM kill with a single reply, and because
+ * a `Content-Length` header is advisory (absent on chunked encoding, and freely
+ * falsifiable) no pre-screen closes that hole. Streaming chunk-by-chunk and
+ * aborting the instant the cap is crossed is the only check that actually bounds
+ * the allocation.
+ *
+ * The scraper has read HTML and PDF this way for some time; these helpers exist so
+ * the JSON API clients share that one implementation rather than each growing a
+ * near-copy of it.
+ */
+
+/** Thrown by {@link readBodyCapped} when a streamed body crosses its byte cap. */
+export class BodyTooLargeError extends Error {
+  constructor(public readonly bytesRead: number, public readonly maxBytes: number) {
+    super(`Response body exceeded ${maxBytes} byte cap`);
+    this.name = 'BodyTooLargeError';
+  }
+}
+
+/**
+ * Default cap for a JSON API response.
+ *
+ * Every endpoint behind these clients answers in kilobytes for a normal query, so
+ * 32MB is orders of magnitude of headroom for legitimate traffic while still
+ * bounding a runaway body to something a Node heap absorbs without dying. Bulk
+ * endpoints that legitimately return more (a full vulnerability catalogue, a
+ * maximum-size CVE page) pass their own larger cap explicitly.
+ */
+export const MAX_JSON_BODY_BYTES = 32 * 1024 * 1024;
+
+/**
+ * Cap for bulk catalogue downloads (CISA KEV's full feed, a 2000-item NVD page).
+ * These are legitimately tens of megabytes and grow over time, so they get their
+ * own ceiling rather than forcing the shared default up for everyone.
+ */
+export const MAX_BULK_JSON_BODY_BYTES = 96 * 1024 * 1024;
+
+/**
+ * Read a response body with a HARD byte cap, streaming chunk-by-chunk so an
+ * over-limit body aborts the moment the cap is crossed.
+ *
+ * A body-less response (test doubles, some mocks) falls back to `arrayBuffer()`;
+ * callers that had a post-read size check keep it as the belt for that path.
+ */
+export async function readBodyCapped(response: Response, maxBytes: number): Promise<Uint8Array> {
+  const body = response.body;
+  // Also tolerate non-standard doubles that expose a body without getReader.
+  if (!body || typeof body.getReader !== 'function') {
+    return new Uint8Array(await response.arrayBuffer());
+  }
+
+  const reader = body.getReader();
+  const chunks: Uint8Array[] = [];
+  let total = 0;
+  try {
+    for (;;) {
+      const { done, value } = await reader.read();
+      if (done) break;
+      if (value) {
+        total += value.byteLength;
+        if (total > maxBytes) throw new BodyTooLargeError(total, maxBytes);
+        chunks.push(value);
+      }
+    }
+  } finally {
+    // Over-cap or downstream throw: release the connection instead of leaving
+    // the socket open (and the server still sending) until GC. No-op after a
+    // clean done=true read.
+    try { await reader.cancel(); } catch { /* already closed */ }
+  }
+  const out = new Uint8Array(total);
+  let offset = 0;
+  for (const c of chunks) { out.set(c, offset); offset += c.byteLength; }
+  return out;
+}
+
+/**
+ * Whether this response can actually be read as a stream — i.e. whether the cap
+ * can be enforced at all.
+ *
+ * A real `Response` from `fetch()` always exposes a `ReadableStream` body except
+ * for the null-body statuses (204/205/304), which have nothing to cap. So in
+ * production this is true exactly when there are bytes to bound, and the capped
+ * path is never quietly skipped. It returns false only for the null-body statuses
+ * and for hand-rolled test doubles, which implement whichever of
+ * `arrayBuffer()`/`text()`/`json()` they need and no stream at all.
+ */
+function hasStreamBody(response: Response): boolean {
+  const body = response.body;
+  return !!body && typeof body.getReader === 'function';
+}
+
+/**
+ * Capped replacement for `response.text()`.
+ *
+ * Decodes UTF-8 non-fatally, matching `Response.text()` — a malformed byte becomes
+ * U+FFFD rather than throwing, so swapping this in cannot turn a body that used to
+ * parse into an exception.
+ */
+export async function readTextCapped(
+  response: Response,
+  maxBytes: number = MAX_JSON_BODY_BYTES,
+): Promise<string> {
+  if (hasStreamBody(response)) {
+    return new TextDecoder('utf-8').decode(await readBodyCapped(response, maxBytes));
+  }
+  // Double/null-body ladder — see hasStreamBody for why this is unreachable for a
+  // real body-bearing response.
+  if (typeof response.arrayBuffer === 'function') {
+    return new TextDecoder('utf-8').decode(new Uint8Array(await response.arrayBuffer()));
+  }
+  return response.text();
+}
+
+/**
+ * Capped replacement for `response.json()`.
+ *
+ * Throws {@link BodyTooLargeError} for an over-cap body and a `SyntaxError` for a
+ * malformed one, so callers that already distinguish "malformed JSON" from other
+ * failures keep working: the size failure is a distinct, catchable type rather
+ * than something that masquerades as a parse error.
+ */
+export async function readJsonCapped<T = unknown>(
+  response: Response,
+  maxBytes: number = MAX_JSON_BODY_BYTES,
+): Promise<T> {
+  if (hasStreamBody(response) || typeof response.arrayBuffer === 'function' || typeof response.text === 'function') {
+    return JSON.parse(await readTextCapped(response, maxBytes)) as T;
+  }
+  // A double that implements json() alone.
+  return response.json() as Promise<T>;
+}
+
+/**
+ * Accumulator for a Node `IncomingMessage` body that decodes UTF-8 exactly ONCE,
+ * at the end.
+ *
+ * The obvious `body += chunk` is silently lossy. `+=` stringifies each Buffer on
+ * its own, so a multi-byte character straddling a chunk boundary is decoded as two
+ * independent fragments and both halves become U+FFFD. Chunk boundaries fall
+ * wherever the socket happens to split, so the damage scales with payload size and
+ * lands only on non-ASCII text — measured at ~15 mangled characters in a 560KB CJK
+ * body. Nothing throws: `JSON.parse` still succeeds, so the corruption reaches the
+ * report and the knowledge store unannounced.
+ *
+ * Buffering the chunks and concatenating before a single decode is what makes a
+ * split sequence whole again.
+ *
+ * `byteLength` counts real bytes, which is also the honest unit for a payload cap —
+ * the old `body.length` measured UTF-16 code units of an already-corrupted string.
+ */
+export class Utf8Body {
+  private readonly chunks: Buffer[] = [];
+  private bytes = 0;
+
+  /** Total bytes accumulated so far. */
+  get byteLength(): number {
+    return this.bytes;
+  }
+
+  push(chunk: Buffer): void {
+    this.chunks.push(chunk);
+    this.bytes += chunk.byteLength;
+  }
+
+  /** Concatenate and decode. Safe to call once the stream has ended. */
+  toString(): string {
+    return Buffer.concat(this.chunks).toString('utf8');
+  }
+}

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;