@lincoln504/pi-research 1.6.5 → 1.6.7

package/src/orchestration/session-state.ts

@@ -88,11 +88,32 @@ function getPiState(piSessionId: string | undefined): PiSessionState {
   return state;
 }
 
+/**
+ * Read-only lookup: returns the session's state WITHOUT creating one for an
+ * unknown/ended piSessionId. Read paths must use this — getPiState() on a
+ * diagnostic/late read for an already-ended session resurrects a full
+ * PiSessionState (four Maps, arrays, timer slots) that only endResearchSession
+ * or clearAllSessionState removes: a slow leak in a long-lived host, and a
+ * violation of the same peek-vs-create discipline ResearchSessionService and
+ * ResearchSynthesisService already enforce ("read/delete paths must never
+ * resurrect").
+ */
+function peekPiState(piSessionId: string | undefined): PiSessionState | null {
+  return piSessions.get(normalizeSessionId(piSessionId)) ?? null;
+}
+
 /**
  * Add a steering message to a Pi session
  */
 export function addSteeringMessage(piSessionId: string | undefined, message: string): void {
   const sid = normalizeSessionId(piSessionId);
+  if (!piSessionId) {
+    // Steering is scoped by piSessionId; a falsy one collapses to the shared
+    // 'default' sid, where two concurrent runs that both omitted it would
+    // consume and inject EACH OTHER's guidance. In-repo callers always pass a
+    // real id — make an SDK caller's contract violation loud at the boundary.
+    logger.warn('[session-state] addSteeringMessage called without a piSessionId — steering collapsed to the shared "default" scope and may cross-talk between concurrent runs.');
+  }
   const state = getPiState(sid);
 
   // Cap per-message length. All active steering is re-sent to the evaluator every
@@ -308,6 +329,10 @@ export function hasQueuedSteeringMessages(piSessionId: string | undefined): bool
  */
 export function onSessionOrderChange(piSessionId: string | undefined, callback: () => void): () => void {
   const sid = normalizeSessionId(piSessionId);
+  // Deliberately CREATE-on-read (the one exception to peekPiState): a
+  // subscription registered BEFORE the session's first write must survive to
+  // see it — peeking here would attach to nothing and silently never fire.
+  // The state object this creates is the same one later writers mutate.
   const state = getPiState(sid);
   state.subscribers.push(callback);
   return () => {
@@ -397,7 +422,8 @@ export function hideMasterWidget(piSessionId: string | undefined): void {
  */
 export function refreshAllSessions(piSessionId: string | undefined): void {
   const sid = normalizeSessionId(piSessionId);
-  const state = getPiState(sid);
+  const state = peekPiState(sid);
+  if (!state) return; // nothing was ever created for this session — nothing to refresh
 
   if (state.refreshTimeout) {
     clearTimeout(state.refreshTimeout);
@@ -632,8 +658,11 @@ export function recordResearcherFailure(piSessionId: string | undefined, researc
  */
 export function getResearcherFailureReasons(piSessionId: string | undefined, researchId: string): Record<string, string> {
   const sid = normalizeSessionId(piSessionId);
-  const state = getPiState(sid);
-  const reasons = state.failureReasons.get(researchId);
+  // Peek, never create: this is a read path (getFailedResearchers below is the
+  // sibling). A read for an ended/never-created session must not resurrect a
+  // PiSessionState keyed by a random sessionId and leak it for process lifetime.
+  const state = peekPiState(sid);
+  const reasons = state?.failureReasons.get(researchId);
   return reasons ? Object.fromEntries(reasons) : {};
 }
 
@@ -642,8 +671,8 @@ export function getResearcherFailureReasons(piSessionId: string | undefined, res
  */
 export function getFailedResearchers(piSessionId: string | undefined, researchId: string): string[] {
   const sid = normalizeSessionId(piSessionId);
-  const state = getPiState(sid);
-  const failures = state.failures.get(researchId) || [];
+  const state = peekPiState(sid);
+  const failures = state?.failures.get(researchId) || [];
   return [...new Set(failures)];
 }
 
@@ -680,8 +709,8 @@ export function getResearchStopMessage(piSessionId: string | undefined, research
   // blocking.
   // Lead with the RECORDED errors when we have them — the actual root cause
   // (e.g. a provider 429) beats generic guidance every time.
-  const state = getPiState(sid);
-  const reasons = state.failureReasons.get(researchId);
+  const state = peekPiState(sid);
+  const reasons = state?.failureReasons.get(researchId);
   const recorded = reasons && reasons.size > 0
     ? ['Recorded errors:', ...[...reasons].map(([id, r]) => `• researcher ${id}: ${r}`), '']
     : [];

package/src/prompts/research-tool-usage.md

@@ -85,7 +85,8 @@ The coordinator will plan as many researchers as needed (up to the max). You do
 
 **Multiple Topics:**
 - If you need to research multiple unrelated topics of **truly distinct scope**, you may emit multiple `research` calls **simultaneously in a single turn**. Each call gets its own isolated research run with its own coordinator and researchers.
-- **Maximum 4 simultaneous calls** — Do NOT make more than 4 `research` calls in a single turn, even if you have more unrelated topics. Exceeding 4 simultaneous research runs can overload the system and degrade performance. If you have more than 4 truly distinct topics, they can likely be consolidated into fewer calls (group related subtopics, use broader queries, or batch across multiple turns).
+- **Maximum 4 simultaneous calls** — Do NOT make more than 4 `research` calls in a single turn, even if you have more unrelated topics. Exceeding 4 simultaneous research runs can overload the system and degrade performance. If you have more than 4 truly distinct topics, they can likely be consolidated into fewer calls (group related subtopics, use broader queries, or batch across multiple turns). Treat the machine-wide run cap (next bullet) as the REAL ceiling: it may be lower than 4, and it always wins.
+- **Simultaneous calls are also bounded by the machine-wide run cap (default 3, `PI_RESEARCH_MAX_CONCURRENT_RUNS`).** A call beyond the cap WAITS for a free slot and fails with a capacity error if the wait expires — so do not count on more than 3 running at once, and never rely on the 4-call maximum being available.
 - Example: `research("bananas")` and `research("quantum computing")` in the same turn — these have zero overlap.
 - **Group related topics**: If topics share ANY scope or could inform each other, combine them into a single `research` call. The internal coordinator will decompose them into parallel researcher agents. Do NOT split related sub-topics into separate calls.
 - Example: `research("Python async performance and Rust async performance comparison")` — NOT separate calls for Python and Rust, since the comparison IS the research goal.

package/src/prompts/researcher.md

@@ -50,7 +50,7 @@ Write your report immediately after scraping is complete, or as soon as a tool r
   - `youtube_transcript`: Read the captions/transcript of YouTube videos from your source list — it is the `scrape` for video. ONE call only, batching up to a few of the most relevant YouTube links. Cite these as `Source: YouTube Transcript`.
   - `stackexchange`: Use ONLY for Stack Overflow or Stack Exchange URLs.
   - `security_search`: Query NVD, CVE, OSV, CISA databases.
-  - `read` / `grep`: Read files and search text in the local codebase. Use ONLY if local codebase context is explicitly required.
+  - `read`: Read files in the local codebase. Use ONLY if local codebase context is explicitly required.
 {{extra_tool_guidelines}}
 
 - **Specialized Tooling Directive**: Do NOT waste time with auxiliary tools (`stackexchange`, `security_search`) unless they are **specifically necessary** for your assigned goal. They are not for exploratory steps. Your primary workflow is to **scrape** authoritative web sources and **report** findings.

package/src/prompts/system-coordinator.md

@@ -43,7 +43,7 @@ Before splitting the query into researchers, pin down its scope — exactly what
 
 ## Output Format
 
-Return ONLY a JSON block containing your full team plan. Use this general schema:
+Respond with your full team plan by CALLING the `submit_plan` tool when it is offered in the conversation — its arguments ARE the plan (primary, schema-exact channel). Only if you cannot call tools, return a JSON block instead. Use this general schema:
 
 ```json
 {
@@ -72,4 +72,4 @@ Return ONLY a JSON block containing your full team plan. Use this general schema
 - **Researcher IDs**: Use Round.Index format (e.g. **1.1**, **1.2**).
 - **Citations**: Each researcher's queries should be designed to uncover sources that can be comprehensively cited. Prioritize queries that lead to authoritative references, data, and documented facts.
 - **Title**: Set `"title"` to 1-2 words that best name the core topic (e.g. `"iPhone 15"`, `"React Performance"`, `"PostgreSQL Replication"`). Use proper nouns and brand names where applicable. Do NOT use generic words like "research", "overview", or "options".
-- **Format**: Valid JSON only. No markdown, no explanation outside the JSON block.
+- **Format**: Call `submit_plan` with the plan as its arguments when the tool is offered; otherwise output valid JSON only. No markdown, no explanation outside the JSON block.

package/src/prompts/system-lead-router.md

@@ -119,4 +119,4 @@ When delegating, ensure:
 - **Researcher IDs**: Use Round.Index format — the current round number from the RUN CONTEXT block, then the researcher index. In round 3 that is **3.1**, **3.2**, and so on.
 - **Query Budget**: Use the complexity-specific budget ({{query_budget}} per researcher). Fill each researcher's query budget completely.
 - **Team Size**: Scale researcher count to match the gaps. Use up to {{max_team_size}} researchers when delegating, but a single well-targeted researcher is often sufficient for focused gaps. Don't pad the team when fewer researchers will cover the remaining gaps efficiently.
-- **Format**: ONLY return valid JSON in a code block. Never return report prose.
+- **Format**: Call `submit_routing_decision` with the updated plan as its arguments when the tool is offered; otherwise return ONLY valid JSON in a code block. Never return report prose.

package/src/sdk.ts

@@ -30,7 +30,7 @@ import type {
 import type { IPlanningService } from './core/interfaces/planning-interfaces.ts';
 import type { ResearchObserver, HeadlessObserverOptions } from './core/interfaces/observer-interfaces.ts';
 import type { ResearchPlan } from './core/interfaces/research-plan-types.ts';
-import { HeadlessObserver } from './orchestration/headless-observer.ts';
+import { HeadlessObserver, isHeadlessObserverBag } from './orchestration/headless-observer.ts';
 import type { Model } from '@earendil-works/pi-ai';
 import { type ExtensionContext, ModelRegistry } from '@earendil-works/pi-coding-agent';
 import { logger, createLogger, setLogger } from './logger.ts';
@@ -607,8 +607,10 @@ export async function runDeepResearch(
     }
     throw err;
   } finally {
-    // Free the per-run PiSessionState that shouldStopResearch()/getFailedResearchers()
-    // lazily created (keyed by this run's random sessionId). A long-lived SDK/benchmark
+    // Free the per-run PiSessionState that startResearchSession()/registerSessionAbort()
+    // created for this run (keyed by this run's random sessionId; the read accessors —
+    // getFailedResearchers()/getResearcherFailureReasons()/shouldStopResearch() — only
+    // peek). A long-lived SDK/benchmark
     // process doing thousands of runs would otherwise accumulate one never-freed entry
     // (failures/aborts/panels) per run — only full shutdown reclaimed them before.
     try { endResearchSession(sessionId, researchId); } catch { /* best-effort */ }
@@ -694,7 +696,7 @@ function wrapObserverForOutcomeCapture(
   onPlanned: (count: number) => void,
 ): ResearchObserver {
   const base: ResearchObserver | undefined =
-    observer && typeof (observer as HeadlessObserverOptions).onProgress === 'function' && !(observer instanceof HeadlessObserver)
+    observer && isHeadlessObserverBag(observer)
       ? new HeadlessObserver(observer as HeadlessObserverOptions)
       : (observer as ResearchObserver | undefined);
 
@@ -890,6 +892,12 @@ export async function searchKnowledge(
   if (!Array.isArray(queries) || queries.length === 0) {
     throw new Error('searchKnowledge requires a non-empty array of queries.');
   }
+  if (queries.length > 5) {
+    // Fail-fast, matching the CLI's contract ('knowledge accepts at most 5
+    // queries.') — the previous silent slice(0, 5) dropped input without telling
+    // the caller, the exact advertised-vs-enforced drift this SDK avoids.
+    throw new Error('searchKnowledge accepts at most 5 queries.');
+  }
 
   // Lazily import the tool factory so the SDK bundle stays lean when unused.
   const { createResearchKnowledgeSearchTool } = await import('./tools/research-knowledge-search.ts');

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

@@ -34,7 +34,7 @@ import { Value } from 'typebox/value';
 import { completeSimple } from '../core/llm/pi-ai-completion.ts';
 import type { Model } from '@earendil-works/pi-ai';
 import { recordLlmUsage } from '../utils/llm-usage.ts';
-import { buildSafeOptions, validateAndExtractText } from '../core/llm/llm-utils.ts';
+import { buildSafeOptions, validateAndExtractText, buildConstrainedSubmitTool, completeSimpleStructured } from '../core/llm/llm-utils.ts';
 import { getService, tryGetServiceContainerFromCtx } from '../core/service-registry.ts';
 import { withTimeout } from '../core/llm/llm-timeout.ts';
 import { abortableDelay } from '../web-research/retry-utils.ts';
@@ -497,6 +497,15 @@ export async function runBackgroundExtraction(
   const systemPrompt = user === null ? fill(system) : system;
   const userMessage = user === null ? finalInstruction : `${fill(user)}\n\n${finalInstruction}`;
 
+  // Structured-output path, same pattern as the planner/router: offer the
+  // schema-constrained submit tool (the synthesis response IS a JSON object
+  // validated below), fall back to the text pipeline on a prose answer.
+  const submitSynthesisTool = buildConstrainedSubmitTool(
+    'submit_knowledge_synthesis',
+    'Submit the extracted answer in the required structured format.',
+    ResearchKnowledgeSynthesisResponseSchemaAsTSchema,
+  );
+
   // Phase 4a: Stateless LLM call — no AgentSession, no side-effects.
   // llmTimeout is resolved by the caller from the iface-aware Config so a
   // per-interface overlay (pi.env / cli.env) is honored here.
@@ -509,26 +518,32 @@ export async function runBackgroundExtraction(
   for (;;) {
     attempt++;
     try {
-      const response = await withTimeout(
-        completeSimple(model, {
+      const structured = await withTimeout(
+        completeSimpleStructured(model, {
           systemPrompt,
           messages: [
-            { role: 'user', content: [{ type: 'text', text: userMessage }], timestamp: Date.now() },
+            { role: 'user', content: [{ type: 'text', text: userMessage + `\n\nRespond by calling the ${submitSynthesisTool.name} tool with the extraction as its arguments.` }], timestamp: Date.now() },
           ],
-        }, buildSafeOptions(model, {
+        }, submitSynthesisTool, buildSafeOptions(model, {
           apiKey: auth.apiKey,
           headers: auth.headers,
           signal,
           sessionId,
-        }, maxTokens, thinkingLevel)),
+        }, maxTokens, thinkingLevel), 'Knowledge Extraction'),
         llmTimeout,
         'knowledge-search-extraction',
       );
+      const response = structured.response;
 
       // Track token and cost metrics for the background synthesis call
       recordLlmUsage(model, (response as any).usage, { component: 'knowledge_search' });
 
-      responseText = validateAndExtractText(response, 'Knowledge Extraction');
+      // Tool-call arguments are re-serialized so the SAME parse → coerce →
+      // validate pipeline below runs for both outcomes; text passes through
+      // byte-identical to the previous behavior.
+      responseText = structured.kind === 'toolCall'
+        ? JSON.stringify(structured.args)
+        : structured.text;
       break;
     } catch (err) {
       // A real cancellation propagates immediately — no retry, no fallback.
@@ -582,6 +597,7 @@ export async function runBackgroundExtraction(
       // at repairJsonWithLlm's smaller default (16384). Mirrors the planning-service repairs.
       maxTokens,
       thinkingLevel,
+      timeoutMs: llmTimeout,
       onUsage: (rawUsage) => recordLlmUsage(model, rawUsage, { component: 'knowledge_search' }),
     },
   );

package/src/tools/research-tool-definition.ts

@@ -282,7 +282,7 @@ export function createResearchTool(iface?: ConfigInterface): ToolDefinition {
       // replace it (validateAndSanitizeQuery below rejects an empty query anyway;
       // failing here keeps the message clear and matches the CLI's up-front check).
       if (!query) {
-        return { content: [{ type: 'text', text: 'Error: research requires a query; initialLinks seed URLs for a query but cannot replace it.' }], details: {} };
+        return { content: [{ type: 'text', text: 'Error: research requires a query; initialLinks seeds URLs for the query but cannot replace it.' }], details: {} };
       }
 
       // Each run gets its own isolated registry; session-level counter is incremented

package/src/tools/scrape.ts

@@ -78,7 +78,7 @@ export function createScrapeTool(options: {
   });
 
   const ScrapeParamsSchema = Type.Object({
-    urls: Type.Array(Type.String({ description: 'The URLs to scrape' }), { minItems: 1, maxItems: 20 }),
+    urls: Type.Array(Type.String({ description: `The URLs to scrape (only the first ${MAX_SCRAPE_URLS} are fetched per call; extras are reported under "Not Fetched" rather than silently dropped)` }), { minItems: 1, maxItems: 20 }),
     maxConcurrency: Type.Optional(Type.Number({ default: config.MAX_CONCURRENT_SCRAPES, minimum: 1, maximum: 20 })),
   });
 
@@ -110,6 +110,17 @@ export function createScrapeTool(options: {
     async execute(_callId: string, params: unknown, signal: AbortSignal, _onUpdate: AgentToolUpdateCallback<any>): Promise<AgentToolResult<unknown>> {
       const callStartTime = Date.now();
 
+      // Validate BEFORE spending the budget slot — the doctrine security.ts /
+      // stackexchange.ts / youtube-transcript.ts already follow (a rejected call
+      // must not consume a batch). The limit check used to run first, inverting it.
+      if (!Value.Check(ScrapeParamsSchema, params)) {
+        metrics.increment('tool_scrape_calls_total', 1, { status: 'invalid_params' });
+        return {
+          content: [{ type: 'text', text: 'Invalid parameters for scrape tool. Expected an array of URLs.' }],
+          details: { error: 'invalid_params' },
+        };
+      }
+
       // Rate-limit enforcement (only when tracker is present)
       if (options.tracker) {
         const callCount = options.tracker.getToolCallCount('scrape');
@@ -123,14 +134,6 @@ export function createScrapeTool(options: {
         }
       }
 
-      if (!Value.Check(ScrapeParamsSchema, params)) {
-        metrics.increment('tool_scrape_calls_total', 1, { status: 'invalid_params' });
-        return {
-          content: [{ type: 'text', text: 'Invalid parameters for scrape tool. Expected an array of URLs.' }],
-          details: { error: 'invalid_params' },
-        };
-      }
-
       const p = params as ScrapeParams;
       const rawUrls = p.urls.map(u => u.trim()).filter(u => u.length > 0);
 

package/src/tools/search.ts

@@ -29,7 +29,10 @@ export function createSearchTool(options: {
   const SearchParamsSchema = Type.Object({
     queries: Type.Array(Type.String(), {
         minItems: 1,
-        maxItems: 50,
+        // Honest schema: the runtime cap is 30 (hard-coded below), so the
+        // advertised max must be 30 — a host reading maxItems 50 would compose
+        // up to 50 queries and silently lose 20 of them at the cap.
+        maxItems: 30,
         description: 'A list of 5-30 search queries to execute (minimum 1).'
     }),
   });
@@ -65,12 +68,10 @@ export function createSearchTool(options: {
       let queries = p.queries;
       metrics.increment('tool_search_queries_total', queries.length);
 
-      if (queries.length < 1) {
-        metrics.increment('tool_search_calls_total', 1, { status: 'insufficient_queries' });
-        throw new Error(`Insufficient queries: ${queries.length}. Provide at least 1 highly specific queries.`);
-      }
-
+      // (No min-length check needed: Value.Check above enforces minItems: 1, so
+      // an under-length call is already rejected as invalid_parameters.)
       // Hard cap at the documented 30-query maximum
+      let submittedQueries = queries.length;
       if (queries.length > 30) {
           logger.warn(`[search tool] Capping tool call queries: ${queries.length} → 30`);
           metrics.increment('tool_search_capped_queries_total', queries.length - 30);
@@ -107,6 +108,11 @@ export function createSearchTool(options: {
 
         let markdown = `# Web Search Results (${queries.length} queries)\n\n`;
         markdown += `**Source: Web Search**\n\n`;
+        if (submittedQueries > queries.length) {
+          // In-band so the calling agent knows its input was truncated and can
+          // re-plan with a follow-up search — mirrors scrape.ts's over-cap note.
+          markdown += `> NOTE: ${submittedQueries - queries.length} of ${submittedQueries} submitted queries were dropped by the 30-query cap. Re-run a follow-up search with the remainder if those topics matter.\n\n`;
+        }
         // Untrusted-data boundary: result titles/snippets below are attacker-influenceable (via a
         // page's own <title>/meta). Remind the model in-band that they are data, not instructions —
         // mirrors the scrape tool's banner; defense-in-depth alongside the researcher prompt.

package/src/tools/security.ts

@@ -10,6 +10,7 @@ import { Value } from 'typebox/value';
 import { searchSecurityDatabases } from '../security/index.ts';
 import type { ToolUsageTracker } from '../utils/tool-usage-tracker.ts';
 import { getMaxGatheringCalls } from '../constants.ts';
+import type { Config } from '../config.ts';
 import { metrics } from '../utils/metrics.ts';
 import { isCancellation } from '../utils/cancellation.ts';
 import type { SecuritySearchParams } from '../security/types.ts';
@@ -26,6 +27,10 @@ function truncateDescription(description: string): string {
 export function createSecuritySearchTool(options: {
   ctx: ExtensionContext;
   tracker: ToolUsageTracker;
+  /** The run's resolved config — the gathering-call budget prompt must read the
+   *  SAME overlay-resolved value the tracker enforces, not the ambient default
+   *  (scrape.ts fixed this same advertised-vs-enforced drift). */
+  config?: Config;
 }): ToolDefinition {
 
   const SecuritySearchParamsSchema = Type.Object({
@@ -67,7 +72,7 @@ export function createSecuritySearchTool(options: {
       'Available for looking up CVE IDs, package vulnerabilities, or security advisories.',
       'Supports databases: NVD (340k+ CVEs), CISA KEV (actively exploited), GitHub Advisories (open source), OSV (packages).',
       'Filter by severity, CVE ID, package name, or include only actively exploited vulnerabilities.',
-      `CRITICAL: You are allowed a maximum of ${getMaxGatheringCalls()} gathering calls across your web tools (search, security_search, stackexchange). Use them for breadth.`,
+      `CRITICAL: You are allowed a maximum of ${getMaxGatheringCalls(options.config)} gathering calls across your web tools (search, security_search, stackexchange). Use them for breadth.`,
     ],
     parameters: SecuritySearchParamsSchema,
     executionMode: 'parallel',

package/src/tools/stackexchange.ts

@@ -10,11 +10,16 @@ import { Value } from 'typebox/value';
 import { stackexchangeCommand } from '../stackexchange/index.ts';
 import type { ToolUsageTracker } from '../utils/tool-usage-tracker.ts';
 import { getMaxGatheringCalls } from '../constants.ts';
+import type { Config } from '../config.ts';
 import { isCancellation } from '../utils/cancellation.ts';
 
 export function createStackexchangeTool(options: {
   ctx: ExtensionContext;
   tracker: ToolUsageTracker;
+  /** The run's resolved config — the gathering-call budget prompt must read the
+   *  SAME overlay-resolved value the tracker enforces, not the ambient default
+   *  (scrape.ts fixed this same advertised-vs-enforced drift). */
+  config?: Config;
 }): ToolDefinition {
   const { tracker } = options;
 
@@ -64,7 +69,7 @@ export function createStackexchangeTool(options: {
       'Anonymous access: 300 requests/day. Set STACKEXCHANGE_API_KEY env var for 10,000/day.',
       'Use tags to filter by specific topics.',
       'Use maxPages parameter to control pagination for search results (default: 5 pages).',
-      `CRITICAL: You are allowed a maximum of ${getMaxGatheringCalls()} gathering calls across your web tools (search, security_search, stackexchange). Use them for breadth.`,
+      `CRITICAL: You are allowed a maximum of ${getMaxGatheringCalls(options.config)} gathering calls across your web tools (search, security_search, stackexchange). Use them for breadth.`,
     ],
     parameters: StackExchangeParamsSchema,
     executionMode: 'parallel',

package/src/utils/cancellation.ts

@@ -30,7 +30,40 @@ export function isCancellation(error: unknown, signal?: AbortSignal | null): boo
   if (signal?.aborted) return true;
   if (error instanceof Error && error.name === 'AbortError') return true;
   const message = error instanceof Error ? error.message : String(error);
-  return /^(aborted|the operation was aborted|research (aborted|cancelled|canceled)|operation cancelled|operation canceled)\.?$/i.test(
+  return /^(aborted|(?:the|this) operation was aborted|research (aborted|cancelled|canceled)|operation cancelled|operation canceled)\.?$/i.test(
     message.trim(),
   );
 }
+
+/**
+ * Race `op` against `signal`, resolving `undefined` when the signal fires
+ * first. The LOSER keeps running in the background — this is an abandon, not
+ * a cancel: the op must be safe to leave draining (probes with their own
+ * timeouts, best-effort telemetry) and its eventual result or rejection is
+ * dropped. Callers treating abandonment as "skip the work" keep their abort
+ * handling at the next signal-aware await, exactly where the rest of the run's
+ * abort plumbing expects it.
+ *
+ * The listener is hoisted (defined once, removed in `finally`) so a settled
+ * race can never leak an `abort` listener onto a long-lived run signal — the
+ * same hygiene the orchestrators' capacity-wait races apply.
+ */
+export function raceWithSignal<T>(op: Promise<T>, signal?: AbortSignal | null): Promise<T | undefined> {
+  if (!signal) return op.then((v) => v);
+  if (signal.aborted) {
+    // The op was started eagerly and may still REJECT later; without a handler
+    // attached that rejection surfaces as an unhandledRejection even though the
+    // race already resolved. Swallow it — abandonment drops the outcome by
+    // contract (the op must be safe to leave draining).
+    void op.catch(() => {});
+    return Promise.resolve(undefined);
+  }
+  let onAbort: () => void;
+  const abandoned = new Promise<undefined>((resolve) => {
+    onAbort = () => resolve(undefined);
+    signal.addEventListener('abort', onAbort, { once: true });
+  });
+  return Promise.race([op, abandoned]).finally(() => {
+    signal.removeEventListener('abort', onAbort!);
+  });
+}

package/src/utils/llm-usage.ts

@@ -67,6 +67,14 @@ function warnIfUnpriced(model: Model<any>, tokens: number, cost: number): void {
  * `tokens > 0 || cost > 0`, so a response whose usage is all-zero across the board
  * emits nothing — harmless in practice because cache fields are summed into `tokens`,
  * so a reported cache split implies a nonzero total.
+ *
+ * Accuracy note: for the openai-completions API family (which includes OpenRouter),
+ * pi-ai's usage normalization ALWAYS sets cacheRead/cacheWrite, defaulting missing
+ * upstream fields to 0 — so on those providers a route without prompt caching shows the
+ * counter at 0 rather than omitting it. The 0-vs-absent distinction only holds for APIs
+ * that omit the fields outright. A run showing llm_cache_read_tokens_total stuck at 0
+ * with nonzero input tokens is therefore most simply read as "this route reports no
+ * cached tokens", not "our prompts defeat the cache".
  */
 function recordCacheTokens(parsed: Partial<TokenUsage>, labels: Record<string, string>): void {
   if (typeof parsed.cacheRead === 'number') {

package/src/utils/log-utils.ts

@@ -38,7 +38,7 @@ export function buildDefaultDebugLogPath(): string {
  * Check whether debug/verbose logging is enabled.
  *
  * Reads PI_RESEARCH_DEBUG env var. Config SAVES sync config.DEBUG into this
- * env var (see config.ts buildEnvValues); plain config LOADS do not mutate
+ * env var (see the DEBUG → PI_RESEARCH_DEBUG bridge in config.ts createConfig); plain config LOADS do not mutate
  * process.env, so a DEBUG=true line in config.env enables verbose logging for
  * a process only after a save has run in it — export PI_RESEARCH_DEBUG=true
  * in the environment to guarantee it from process start.

package/src/web-research/browser-search.ts

@@ -331,11 +331,12 @@ export async function performSearch(
             metrics.increment('browser_search_total_failures_total', 1, { cause: 'native_binding' });
             throw new Error(
                 `Search completely failed: ${reason}, all with a missing native module. ` +
-                `This is an incomplete install, not a network problem: the browser engine's ` +
-                `native dependencies were never built. npm 12 does not run dependency install ` +
-                `scripts by default — reinstall allowing the script (global install: ` +
-                `npm install -g @lincoln504/pi-research --allow-scripts=better-sqlite3; ` +
-                `project install: npm approve-scripts better-sqlite3, then npm rebuild better-sqlite3), then retry.` +
+                `This is an incomplete install, not a network problem: better-sqlite3 13 ` +
+                `ships prebuilt bindings for every supported platform and loads them at ` +
+                `runtime, so a missing binding means an old or broken npm install. ` +
+                `Upgrade npm to ≥12 (npm install -g npm@12) and reinstall this package — ` +
+                `modern npm skips the needless recompile that fails on toolchain-less ` +
+                `machines, and the prebuilt binding then loads as-is.` +
                 (sampleWorkerError ? ` Last worker error: ${sampleWorkerError}` : '')
             );
         }