@lincoln504/pi-research 1.4.1 → 1.5.0

package/src/orchestration/researcher.ts

@@ -21,7 +21,7 @@ import type { SystemResearchState } from './deep-research-types.ts';
 import type { Config } from '../config.ts';
 import { logger } from '../logger.ts';
 
-import { resolveResearchModel } from '../core/llm/research-model-resolver.ts';
+import { resolveResearchModel, isPromptCachingActiveForModel } from '../core/llm/research-model-resolver.ts';
 import { getRuntimeForRegistry } from '../core/llm/model-registry-factory.ts';
 import { boundSessionAbort } from './abort-utils.ts';
 
@@ -86,7 +86,7 @@ export async function createResearcherSession(options: CreateResearcherSessionOp
   logger.info(`[Researcher] Using model for researcher ${researcherId}: ${modelToUse.provider}/${modelToUse.id}`);
 
   try {
-    const tracker = new ToolUsageTracker(createDefaultToolLimits(config));
+    const tracker = new ToolUsageTracker(createDefaultToolLimits(config, isPromptCachingActiveForModel(modelToUse)));
 
     // Use provided closures or fallback to safe dummies
     const globalLinks = updateGlobalLinks || (() => {});

package/src/orchestration/session-state.ts

@@ -518,8 +518,22 @@ export function endResearchSession(piSessionId: string | undefined, researchId:
 
   // If this was the last research run in the Pi session, clean up the state
   // but preserve steering messages if any remain (they might arrive between
-  // the last research end and the next research start)
-  if (state.order.length === 0 && state.panels.size === 0) {
+  // the last research end and the next research start).
+  //
+  // `state.aborts` is included alongside `order`/`panels`: those two are
+  // populated ONLY by the TUI path (registerSessionPanel), so for a purely
+  // headless multi-run session they are always empty — including while
+  // OTHER headless runs are still genuinely active. Gating on order/panels
+  // alone made this block treat every single headless run's end as "the
+  // last one," which both cleared `aborts` for still-running siblings
+  // (corrupting getActiveResearchRunCount for any caller relying on it) and,
+  // combined with a caller that clears steering right after seeing count 0,
+  // could wipe a message this very block had just decided to preserve one
+  // statement earlier. `aborts.delete(researchId)` above already removed
+  // this run's own entry, so `aborts.size === 0` here means no run of any
+  // kind (TUI or headless) remains — the same atomic, single-synchronous-
+  // function guarantee `order`/`panels` already had for the TUI-only case.
+  if (state.order.length === 0 && state.panels.size === 0 && state.aborts.size === 0) {
     // Drop steering messages this run already consumed ('active') — and any
     // 'popped' remnants, which are likewise already resolved — before deciding
     // whether to keep the session alive. Without this, a message the run that
@@ -540,10 +554,11 @@ export function endResearchSession(piSessionId: string | undefined, researchId:
       clearPendingRefresh(sid);
       piSessions.delete(sid);
     } else {
-      // Clear research-specific state but preserve the session and steering
+      // Clear research-specific state but preserve the session and steering.
+      // aborts is already empty (the outer gate above requires it), so no
+      // separate clear is needed for it here.
       state.failures.clear();
       state.failureReasons.clear();
-      state.aborts.clear();
     }
   }
 }
@@ -703,6 +718,22 @@ export function getPiActivePanels(piSessionId: string | undefined): ResearchPane
   return [...state.order].reverse().map(id => state.panels.get(id)!).filter(Boolean);
 }
 
+/**
+ * Count of research runs currently active in a Pi session, TUI or headless.
+ *
+ * Unlike getPiActivePanels (populated only by registerSessionPanel, which the
+ * TUI path alone calls), `aborts` is registered by registerSessionAbort on
+ * EVERY run — headless included — and removed only by endResearchSession. Use
+ * this wherever "am I the last/only active run in this session" must hold for
+ * headless callers too (e.g. gating a shared-state clear like steering
+ * messages so a finishing run doesn't wipe a concurrent sibling's).
+ */
+export function getActiveResearchRunCount(piSessionId: string | undefined): number {
+  const sid = normalizeSessionId(piSessionId);
+  const state = piSessions.get(sid);
+  return state ? state.aborts.size : 0;
+}
+
 /**
  * Get the ordered list of active research run IDs in a Pi session.
  * Returns IDs in chronological order (oldest first, newest last).

package/src/prompts/research-knowledge-relevance-triage.md

@@ -18,6 +18,8 @@ Your ONLY job is to decide which candidates are genuinely relevant to the user's
 Field definitions:
 - `relevant_indices` (array of integers, required): the 0-based indices of the relevant candidates, in any order. Empty array `[]` if none are relevant.
 
+<!-- USER_TURN: everything below is delivered as the USER message of the stateless call, not the system prompt. The rules above stay byte-identical across calls so the provider can serve the system prefix from its prompt cache; the sections below vary per call. -->
+
 ## USER'S SEARCH QUERY
 
 Judge each candidate's relevance to this search query. This is the PRIMARY signal for what the user wants; the conversation below is supplementary and may be absent for a direct (non-conversational) search:

package/src/prompts/research-knowledge-search-extractor.md

@@ -24,6 +24,8 @@ Field definitions:
 - `synthesis` (string, optional): The synthesized answer if found. Use inline citation markers [1], [2], etc. that correspond to the citations array. Present when answer_status is "yes" or "maybe". Omit when answer_status is "no".
 - `citations` (array of strings, required): The source URLs from the reference documents that were used to construct the answer. Empty array if answer_status is "no".
 
+<!-- USER_TURN: everything below is delivered as the USER message of the stateless call, not the system prompt. The rules above stay byte-identical across calls so the provider can serve the system prefix from its prompt cache; the sections below vary per call. -->
+
 ## USER'S SEARCH QUERY
 
 Answer this search query from the reference documents. This is the PRIMARY signal for what the user wants; the conversation below is supplementary and may be absent for a direct (non-conversational) search:

package/src/prompts/researcher.md

@@ -2,7 +2,7 @@
 
 <!-- RESEARCHER_AGENT_MARKER -->
 
-You are an autonomous research agent. Your goal is to investigate your assigned topic with depth and rigor.
+You are an autonomous research agent. Your goal is to investigate your assigned topic with depth and rigor. Your specific goal, any historical knowledge-store results, your initial evidence/search results, and any sibling-coordination notes are provided in the user message that follows this system prompt — not here, so this system prompt stays byte-identical across every researcher and round (prompt caching).
 
 ## CORE DIRECTIVES (Strict Enforcement)
 
@@ -23,20 +23,10 @@ Do not treat any source as inherently objective. Justify its inclusion through t
 
 ---
 
-## Your Goal
-{{goal}}
-
-{{store_section}}
-(Note: when knowledge-store results appear above, they were retrieved automatically for your goal, aggregated from the **Project Knowledge Store** and **User Knowledge Store**. Do NOT try to search the store manually.)
-
-{{evidence_section}}
-
----
-
 ## Workflow
 
 ### Step 1: Build Your Source List
-Combine historical URLs and search results into a unified pool. Use previous session summaries as a guide for what to expect.
+Combine historical URLs and search results into a unified pool. Use previous session summaries as a guide for what to expect. Any knowledge-store results in your user message were retrieved automatically for your goal from the **Project Knowledge Store** and/or **User Knowledge Store** — cite them with that store name as their `Source:`.
 
 ### Step 2: Scrape Round 1
 Identify the 4 most promising URLs and scrape them in one batch (the scrape tool accepts up to 6 per call; 4 is your target per round). Prioritize primary sources, authoritative references, and dense documentation; all else being equal, lean toward more recent / current sources and topics.
@@ -51,8 +41,6 @@ Do NOT scrape URLs directly from the pool — only scrape URLs from your own sou
 ### Step 4: Synthesize
 Write your report immediately after scraping is complete, or as soon as a tool reports its limit is reached (e.g. "GATHERING LIMIT REACHED", "SEARCH LIMIT REACHED", "SCRAPE PROTOCOL COMPLETE"). Make no further tool calls after beginning synthesis.
 
-{{coordination_section}}
-
 ---
 
 ## Guidelines

package/src/sdk.ts

@@ -111,6 +111,7 @@ let _onSignal: ((signal: string) => void) | null = null;
 let _sigintHandler: (() => void) | null = null;
 let _sigtermHandler: (() => void) | null = null;
 let _sighupHandler: (() => void) | null = null;
+let _sigquitHandler: (() => void) | null = null;
 let _sigbreakHandler: (() => void) | null = null;
 let _shuttingDown = false;
 // In-flight shutdown guard. A cooperative shutdownResearchSDK() can race a
@@ -147,9 +148,13 @@ function _registerSignalHandlers(): void {
   _sigintHandler  = () => _onSignal?.('SIGINT');
   _sigtermHandler = () => _onSignal?.('SIGTERM');
   _sighupHandler  = () => _onSignal?.('SIGHUP');
+  _sigquitHandler = () => _onSignal?.('SIGQUIT');
   process.on('SIGINT',  _sigintHandler);
   process.on('SIGTERM', _sigtermHandler);
   process.on('SIGHUP',  _sighupHandler);
+  // SIGQUIT has no Windows equivalent; registering the listener there is a
+  // documented no-op (Node never delivers it), so no platform guard is needed.
+  process.on('SIGQUIT', _sigquitHandler);
   if (process.platform === 'win32') {
     _sigbreakHandler = () => _onSignal?.('SIGBREAK');
     process.on('SIGBREAK', _sigbreakHandler);
@@ -160,6 +165,7 @@ function _removeSignalHandlers(): void {
   if (_sigintHandler)   { process.removeListener('SIGINT',   _sigintHandler);   _sigintHandler   = null; }
   if (_sigtermHandler)  { process.removeListener('SIGTERM',  _sigtermHandler);  _sigtermHandler  = null; }
   if (_sighupHandler)   { process.removeListener('SIGHUP',   _sighupHandler);   _sighupHandler   = null; }
+  if (_sigquitHandler)  { process.removeListener('SIGQUIT',  _sigquitHandler);  _sigquitHandler  = null; }
   if (_sigbreakHandler) { process.removeListener('SIGBREAK', _sigbreakHandler); _sigbreakHandler = null; }
   _onSignal = null;
 }
@@ -369,6 +375,16 @@ async function _doInit(options: ResearchSDKOptions = {}): Promise<void> {
  * Public initialization. Guarantees the SDK is ready for use.
  */
 export async function initResearchSDK(options: ResearchSDKOptions = {}): Promise<void> {
+  // A shutdown may be in flight: isInitialized only flips to false near the END
+  // of _doShutdown (after container disposal), so without this a caller racing a
+  // shutdown would hit the isInitialized branch below, log its "already
+  // initialized" warning, and return believing the SDK is ready — while the
+  // container it would use is mid-teardown or about to be nulled out from under
+  // it. Wait the shutdown out first so this call observes the real post-shutdown
+  // state, mirroring shutdownResearchSDK's symmetric wait on _initPromise.
+  if (_shutdownPromise) {
+    await _shutdownPromise.catch(() => { /* a failed shutdown must not block a fresh init */ });
+  }
   if (isInitialized) {
     logger.warn('[SDK] Research SDK already initialized. Call shutdownResearchSDK() first if you want to re-initialize with new options.');
     return;

package/src/skill-install/skill-installer.ts

@@ -480,7 +480,11 @@ export function uninstallSkill(toolIds?: string[], opts: InstallOptions = {}): U
   }
 
   for (const { tool, path: skillPath } of targets.values()) {
-    if (toolIds && toolIds.length && !toolIds.includes(tool)) {
+    // undefined = every manifest entry; an explicit (including empty) list means
+    // exactly those tools. `toolIds.length` used to gate this, so `[]` was
+    // indistinguishable from `undefined` and silently uninstalled everything —
+    // inconsistent with this file's other list params, where empty means none.
+    if (toolIds !== undefined && !toolIds.includes(tool)) {
       const e = manifest.entries.find(x => x.path === skillPath);
       if (e) keep.push(e);
       continue;

package/src/stackexchange/index.ts

@@ -27,6 +27,7 @@ import {
 } from './output/compact.ts';
 import type { ExtensionContext, AgentToolResult } from '@earendil-works/pi-coding-agent';
 import { logger } from '../logger.ts';
+import { metrics } from '../utils/metrics.ts';
 
 function notify(
   ctx: ExtensionContext,
@@ -86,6 +87,7 @@ export async function stackexchangeCommand(options: {
   try {
     // Check quota before making requests
     if (client.isQuotaExhausted()) {
+      metrics.increment('stackexchange_quota_exhausted_total', 1);
       const quota = client.getQuotaInfo();
       notify(
         ctx,
@@ -103,6 +105,7 @@ export async function stackexchangeCommand(options: {
 
     // Warn if quota is low
     if (client.isQuotaLow()) {
+      metrics.increment('stackexchange_quota_low_total', 1);
       const quota = client.getQuotaInfo();
       notify(
         ctx,

package/src/stackexchange/rest-client.ts

@@ -193,24 +193,19 @@ export class StackExchangeClient {
     });
   }
 
+  // Pure accessor — no metrics side effects. `stackexchangeCommand()` calls this
+  // repeatedly per invocation (pre-request gate checks, success footer, error
+  // footer) purely to read current state for display; incrementing counters here
+  // used to record 2-3x the real number of quota-low/exhausted events per call.
+  // The counters are incremented once, at the single gate check that actually
+  // observes each event (see stackexchange/index.ts).
   getQuotaInfo(): { remaining: number; max: number; requestCount: number; lastBackoff: number | null } {
-    const info = {
+    return {
       remaining: this.quotaRemaining,
       max: this.quotaMax,
       requestCount: this.requestCount,
       lastBackoff: this.lastBackoff,
     };
-    
-    // Track quota exhaustion events
-    if (this.isQuotaExhausted()) {
-      metrics.increment('stackexchange_quota_exhausted_total', 1);
-    }
-    
-    if (this.isQuotaLow()) {
-      metrics.increment('stackexchange_quota_low_total', 1);
-    }
-    
-    return info;
   }
 
   isQuotaExhausted(): boolean {

package/src/tools/index.ts

@@ -6,7 +6,8 @@
  *
  * NOTE: `research_knowledge_search` is NOT included here. It is a top-level tool
  * registered via pi.registerTool() in src/index.ts. Researcher sub-agents
- * already receive knowledge store data via the store_section prompt injection.
+ * already receive knowledge-store data in their initial user message (see
+ * researcher-executor.ts / quick-research-orchestrator.ts).
  */
 
 import type { ToolDefinition, ExtensionContext } from '@earendil-works/pi-coding-agent';

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

@@ -427,6 +427,27 @@ export function isTransientSynthesisError(message: string): boolean {
   );
 }
 
+/**
+ * Split a knowledge-search prompt template at its USER_TURN marker into the
+ * static system-prompt part (the rules, byte-identical across calls so the
+ * provider can serve it from its prompt cache) and the per-call user-message
+ * part (where the {{...}} placeholders live). If the marker is absent —
+ * a shipped-file regression — returns the whole template as `system` and
+ * `user: null`, and the caller falls back to the legacy all-in-system shape,
+ * which is functionally correct (just uncacheable).
+ * Exported for unit testing.
+ */
+export function splitPromptAtUserTurn(template: string): { system: string; user: string | null } {
+  const open = template.indexOf('<!-- USER_TURN');
+  if (open < 0) return { system: template, user: null };
+  const close = template.indexOf('-->', open);
+  if (close < 0) return { system: template, user: null };
+  return {
+    system: template.slice(0, open).trimEnd(),
+    user: template.slice(close + '-->'.length).trimStart(),
+  };
+}
+
 /** Exported for unit testing of the transient-retry loop. */
 export async function runBackgroundExtraction(
   model: Model<any>,
@@ -452,13 +473,20 @@ export async function runBackgroundExtraction(
   // plain string replacement interprets `$&`, `` $` ``, `$'`, `$$` as substitution patterns and
   // corrupts the extractor prompt (duplicating/eating template text) → wrong yes/maybe/no
   // classification. A function replacer inserts the value literally. (Same class as commit 78c16f98.)
-  const systemPrompt = promptTemplate
+  //
+  // The template splits at USER_TURN: the static rules become the system prompt
+  // (byte-identical across calls → prompt-cache reads instead of a fresh cache
+  // write per call) and the per-call sections go in the user message.
+  const { system, user } = splitPromptAtUserTurn(promptTemplate);
+  const fill = (t: string): string => t
     .replace('{{queries}}', () => formatQueriesBlock(queries))
     .replace('{{conversation_history}}', () => conversationHistory)
     .replace('{{reference_documents}}', () => referenceDocuments);
 
-  const userMessage =
+  const finalInstruction =
     'Analyze the reference documents above and extract the answer using the required JSON format.';
+  const systemPrompt = user === null ? fill(system) : system;
+  const userMessage = user === null ? finalInstruction : `${fill(user)}\n\n${finalInstruction}`;
 
   // Phase 4a: Stateless LLM call — no AgentSession, no side-effects.
   // llmTimeout is resolved by the caller from the iface-aware Config so a
@@ -611,12 +639,17 @@ export async function triageRelevantUrls(
 
   // FUNCTION replacers so literal `$`/`$&` in queries, descriptions or history are not
   // treated as regex substitution patterns (same class as the synthesis prompt).
-  const systemPrompt = promptTemplate
+  // Split at USER_TURN like the extractor: static rules stay in the system prompt
+  // (cacheable across calls), per-call sections go in the user message.
+  const { system, user } = splitPromptAtUserTurn(promptTemplate);
+  const fill = (t: string): string => t
     .replace('{{queries}}', () => formatQueriesBlock(queries))
     .replace('{{conversation_history}}', () => conversationHistory)
     .replace('{{candidates}}', () => candidateBlock);
 
-  const userMessage = 'Return the JSON object listing the indices of the relevant candidates.';
+  const finalInstruction = 'Return the JSON object listing the indices of the relevant candidates.';
+  const systemPrompt = user === null ? fill(system) : system;
+  const userMessage = user === null ? finalInstruction : `${fill(user)}\n\n${finalInstruction}`;
 
   let responseText: string;
   let attempt = 0;

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

@@ -17,6 +17,7 @@ import type {
 import type { ExtendedExtensionContext } from '../types/extension-context.ts';
 import type { ResearchDepth, CleanupContext } from '../types/index.ts';
 import { Type, type Static } from 'typebox';
+import { Value } from 'typebox/value';
 import { validateConfig, getConfig, type ConfigInterface } from '../config.ts';
 import { tryGetServiceContainerFromCtx, getService } from '../core/service-registry.ts';
 
@@ -28,11 +29,12 @@ import { redactSecrets } from '../utils/log-utils.ts';
 import { exportResearchReport, appendExportMessage } from '../utils/research-export.ts';
 import { validateAndSanitizeQuery } from '../utils/input-validation.ts';
 import { validateInitialLinks, MAX_INITIAL_LINKS, MAX_INITIAL_LINK_CHARS } from '../utils/url-utils.ts';
-import { startResearchSession, endResearchSession, registerSessionAbort, clearSteeringMessages, getPiActivePanels } from '../orchestration/session-state.ts';
+import { startResearchSession, endResearchSession, registerSessionAbort } from '../orchestration/session-state.ts';
 import { createResearchTuiManager, hideWorkingIndicator } from '../tui/research-tui-manager.ts';
 import { createCleanupFunction } from '../cleanup/research-cleanup.ts';
 import { createResearchObserver, createObserverState, stopObserverWaveAnimation } from '../observers/research-observer-impl.ts';
 import { HeadlessObserver } from '../orchestration/headless-observer.ts';
+import { isPromptCachingActiveForModel } from '../core/llm/research-model-resolver.ts';
 
 import { ensureFunctionalHealth, createHealthMonitor } from '../tui/research-health.ts';
 import { ErrorTracker, runWithTracker, type ErrorReport } from '../utils/error-tracker.ts';
@@ -118,6 +120,21 @@ export function createResearchTool(iface?: ConfigInterface): ToolDefinition {
 
   type ResearchParams = Static<typeof parameters>;
 
+  // Same field shapes as `parameters`, but WITHOUT the initialLinks count/length
+  // bounds — used only for the runtime execute() gate below. validateInitialLinks
+  // already enforces those same two bounds with a specific, friendly message
+  // ("at most N URLs...", "at most N characters..."); checking them again here
+  // would just produce the generic 'invalid_parameters' rejection first and mask
+  // that better message. Structural type-checking (initialLinks must still be an
+  // array of strings) is kept, since validateInitialLinks assumes that shape.
+  const executeShapeCheck = Type.Object({
+    query: Type.String(),
+    depth: Type.Optional(Type.Integer({ minimum: 1, maximum: 3 })),
+    model: Type.Optional(Type.String()),
+    excludeTools: Type.Optional(Type.Array(Type.String())),
+    initialLinks: Type.Optional(Type.Array(Type.String())),
+  });
+
   return {
     name: 'research',
     label: 'Research',
@@ -169,6 +186,17 @@ export function createResearchTool(iface?: ConfigInterface): ToolDefinition {
         };
       }
 
+      // Every other tool in this codebase re-validates params against its own
+      // schema before trusting it (the host does not enforce this) — this was the
+      // one exception, relying entirely on incidental downstream checks (a
+      // typeof on query, a warn-gate on excludeTools) for fields that skip both.
+      if (!Value.Check(executeShapeCheck, params)) {
+        return {
+          content: [{ type: 'text', text: 'Error: invalid parameters for research tool.' }],
+          details: { error: 'invalid_parameters' },
+        };
+      }
+
       const { query, depth: rawDepth, model: modelId, excludeTools: paramExcludeTools, initialLinks } = params as ResearchParams;
 
       // Enforce the same bounds the CLI applies to --initial-links: these links are
@@ -225,17 +253,21 @@ export function createResearchTool(iface?: ConfigInterface): ToolDefinition {
         if (observerState && panelState) {
           try { stopObserverWaveAnimation(observerState, panelState); } catch (e) { logger.error('[research] Stop wave animation failed:', e); }
         }
-        // Steering messages are shared per pi-session. Only reset them when THIS is
-        // the last active run — otherwise a finishing run wipes a concurrent sibling
-        // run's queued/active steering mid-flight. This run's panel is still
-        // registered here (endResearchSession runs later in cleanup()), so a count
-        // of <= 1 means no other run is active.
-        try {
-          if (getPiActivePanels(piSessionId).length <= 1) clearSteeringMessages(piSessionId);
-        } catch (e) { logger.error('[research] Clear steering messages failed:', e); }
         if (detachAbortListener) {
           try { detachAbortListener(); } catch { /* best-effort */ } finally { detachAbortListener = undefined; }
         }
+        // cleanup() calls endResearchSession (directly in the headless closure,
+        // or via createCleanupFunction for TUI), which deregisters this run and,
+        // in the same synchronous call, decides whether it was the last active
+        // run (TUI or headless) in the pi-session and — only then — resets
+        // steering messages (preserving any still-genuinely-queued ones for the
+        // next run, dropping only ones this run already consumed). That single
+        // synchronous function is the right place for this decision: a separate
+        // check-then-clear here, even ordered after cleanup(), raced ahead of or
+        // fought with endResearchSession's own last-run/preserve logic — either
+        // reading stale counts before two racing siblings had both deregistered,
+        // or unconditionally wiping a message endResearchSession had just decided
+        // to preserve. See endResearchSession in session-state.ts.
         if (cleanup) {
           try { await cleanup(); } catch (cleanupError) { logger.error('[research] Cleanup failed:', cleanupError); }
         }
@@ -328,7 +360,16 @@ export function createResearchTool(iface?: ConfigInterface): ToolDefinition {
             // Setup TUI observer
             observerState = createObserverState();
             observer = createResearchObserver(
-              { panelState, debouncedRefresh: () => tuiManager?.debouncedRefresh(), renderImmediate: () => tuiManager?.renderImmediate(), researchComplexity: depth ?? 1 },
+              {
+                panelState,
+                debouncedRefresh: () => tuiManager?.debouncedRefresh(),
+                renderImmediate: () => tuiManager?.renderImmediate(),
+                researchComplexity: depth ?? 1,
+                // Progress units are relative to the EFFECTIVE scrape-batch count,
+                // which is one higher when prompt caching is active for the run's
+                // resolved model — same value the researchers' trackers enforce.
+                cachingActive: isPromptCachingActiveForModel(selectedModel),
+              },
               observerState
             );
           } else {
@@ -344,9 +385,10 @@ export function createResearchTool(iface?: ConfigInterface): ToolDefinition {
               // module-level piSessions map keyed by the STABLE pi session id, so
               // without this every headless run leaked them for the process
               // lifetime (the TUI branch frees them via createCleanupFunction, the
-              // SDK in its own finally; this branch freed only steering).
+              // SDK in its own finally). endResearchSession itself decides whether
+              // this was the last active run (TUI or headless) and, only then,
+              // resets steering messages — see its own comment in session-state.ts.
               endResearchSession(piSessionId, sessionResearchId);
-              clearSteeringMessages(piSessionId);
             };
             
             // Minimal stub — only stopObserverWaveAnimation touches panelState in the

package/src/tools/scrape.ts

@@ -49,7 +49,14 @@ export function createScrapeTool(options: {
   config?: Config;
 }): ToolDefinition {
   const config = options.config || getConfig(options.ctx.cwd);
-  const maxScrapeBatches = getMaxScrapeBatches(config);
+  // Prefer the tracker's own scrape limit when one is present: it was built via
+  // createDefaultToolLimits(config, cachingActive) and so already reflects any
+  // prompt-caching batch bonus (see getMaxScrapeBatches in constants.ts). Without
+  // this, the tool's own description/promptSnippet/protocol text (below) told the
+  // model a lower, non-caching-aware batch count than the tracker actually
+  // enforced — a real, if harmless, missed-opportunity: the model would stop one
+  // batch short of what it was actually allowed to use.
+  const maxScrapeBatches = options.tracker?.getToolLimit('scrape') ?? getMaxScrapeBatches(config);
   const container = tryGetServiceContainerFromCtx(options.ctx);
 
   // Fallback global state when no orchestration context is provided

package/src/tools/security.ts

@@ -98,16 +98,6 @@ export function createSecuritySearchTool(options: {
           };
       }
 
-      // Record call in tracker - returns false if limit reached
-      const allowed = options.tracker.recordCall('security_search');
-      if (!allowed) {
-          metrics.increment('tool_security_search_calls_total', 1, { status: 'rate_limited' });
-          return {
-            content: [{ type: 'text', text: options.tracker.getLimitMessage('security_search') }],
-            details: { blocked: true, reason: 'limit_reached' },
-          };
-      }
-
       const p = params as SecuritySearchParamsType;
 
       const terms = p.terms;
@@ -160,6 +150,19 @@ export function createSecuritySearchTool(options: {
       }
       const maxResults = p.maxResults ?? 20;
 
+      // Record call in tracker - returns false if limit reached. Deliberately AFTER
+      // every semantic-validation reject above (terms/databases/severity), same
+      // reasoning as the schema check: a rejected call did no work and must not
+      // permanently consume one of the researcher's shared MAX_GATHERING_CALLS slots.
+      const allowed = options.tracker.recordCall('security_search');
+      if (!allowed) {
+          metrics.increment('tool_security_search_calls_total', 1, { status: 'rate_limited' });
+          return {
+            content: [{ type: 'text', text: options.tracker.getLimitMessage('security_search') }],
+            details: { blocked: true, reason: 'limit_reached' },
+          };
+      }
+
       metrics.increment('tool_security_search_terms_total', terms.length);
       metrics.increment('tool_security_search_databases_total', databases.length);
 

package/src/utils/coverage-digest.ts

@@ -109,7 +109,7 @@ export interface SplitReport {
  * better than one that reaches it short.
  */
 export function splitCoverageDigest(report: string): SplitReport {
-  if (!report) return { digest: '', body: report ?? '' };
+  if (!report) return { digest: '', body: report };
 
   const headerMatch = delimiterRegex(COVERAGE_DIGEST_HEADER).exec(report);
   if (!headerMatch) return { digest: '', body: report };

package/src/utils/host-config.ts

@@ -27,11 +27,22 @@ let _configDirName: string | undefined;
  * Resolution order: explicit env override (`PI_RESEARCH_CONFIG_DIR_NAME`) →
  * the host `@earendil-works/pi-coding-agent` package (only where it is actually
  * resolvable, i.e. the main pi process) → the stable default `.pi`.
+ *
+ * The override is a directory NAME, not a path: it is joined onto
+ * `os.homedir()` by every caller (getGlobalConfigDir() in config.ts), which in
+ * turn is the base for config.env (API keys, chmod 0600), the state dir
+ * (locks, run semaphores), and the knowledge_db. A value containing a path
+ * separator or `..` traverses out of HOME entirely — scripts/cleanup.cjs
+ * already rejects exactly that in its own copy of this resolution (see its
+ * `rawDirName`/`dirName` guard); this must reject it the same way, since this
+ * is the copy every actual run resolves secrets and state through.
  */
 export function getConfigDirName(): string {
   if (_configDirName !== undefined) return _configDirName;
   const override = process.env['PI_RESEARCH_CONFIG_DIR_NAME'];
-  if (override) return (_configDirName = override);
+  if (override && !override.includes('/') && !override.includes('\\') && override !== '.' && override !== '..') {
+    return (_configDirName = override);
+  }
   try {
     const require = createRequire(import.meta.url);
     const host = require('@earendil-works/pi-coding-agent') as { CONFIG_DIR_NAME?: string };

package/src/utils/log-utils.ts

@@ -37,8 +37,11 @@ export function buildDefaultDebugLogPath(): string {
 /**
  * Check whether debug/verbose logging is enabled.
  *
- * Reads PI_RESEARCH_DEBUG env var. This env var is kept in sync with
- * config.DEBUG whenever the config is loaded or saved (see config.ts).
+ * 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
+ * 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.
  * Set to "true" to enable INFO+DEBUG logs.
  */
 export function isVerboseFromEnv(): boolean {
@@ -255,6 +258,16 @@ export function redactSecrets(message: string): string {
     // never negative; it still prefers the larger rawLength when the
     // REDACT_SCAN_LENGTH cut discarded raw content redaction then shrank.
     out = `${out.slice(0, keep)}…[truncated ${Math.max(rawLength, out.length) - keep} chars]`;
+  } else if (rawLength > scanEnd) {
+    // The scanEnd cut (line 220) already dropped `rawLength - scanEnd` raw
+    // chars before redaction ever ran. If redaction then net-shrinks the
+    // scanned prefix enough that `out.length` no longer exceeds
+    // MAX_LOG_MESSAGE_LENGTH (e.g. many long hex/JWT runs each collapsed to
+    // the short literal '[REDACTED]'), the branch above never fires and this
+    // message would otherwise read as complete — silently hiding the tail of
+    // a large scraped page or provider error body with no indication
+    // anything was cut.
+    out = `${out}…[truncated ${rawLength - scanEnd} chars]`;
   }
   return out;
 }

package/src/utils/metrics-summary.ts

@@ -48,6 +48,12 @@ export interface ResearchStats {
   errors: number;
   /** Total LLM tokens consumed. */
   tokens: number;
+  /** Prompt-cache READ tokens (prompt prefix served from the provider's cache at the
+   *  discounted rate). 0 when the provider reported none or does not report caching. */
+  cacheReadTokens: number;
+  /** Prompt-cache WRITE tokens (prefix stored into the provider's cache, billed at a
+   *  premium). Reads pinned at 0 while writes climb = a caching regression. */
+  cacheWriteTokens: number;
   /** Total cost in USD across all LLM calls. */
   cost: number;
   /** Tool usage counts. */
@@ -193,6 +199,12 @@ export function extractRunStats(snapshot: IMetricsSnapshot): ResearchStats | nul
   // Tokens — sum all label variants
   const tokens = sumCounter(counters, 'llm_tokens_total');
 
+  // Prompt-cache split (recordLlmUsage emits these only when the provider reports
+  // the fields, so 0 here covers both "cache off" and "not reported" — the raw
+  // counters keep those distinguishable for anyone reading the snapshot directly).
+  const cacheReadTokens = sumCounter(counters, 'llm_cache_read_tokens_total');
+  const cacheWriteTokens = sumCounter(counters, 'llm_cache_write_tokens_total');
+
   // Cost — sum all label variants
   const cost = sumCounter(counters, 'llm_cost_total');
 
@@ -251,6 +263,8 @@ export function extractRunStats(snapshot: IMetricsSnapshot): ResearchStats | nul
     urlsFailed,
     errors,
     tokens,
+    cacheReadTokens,
+    cacheWriteTokens,
     cost,
     toolUsage,
   };
@@ -315,7 +329,13 @@ export function buildResearchSummary(stats: ResearchStats): string {
   // --- Resource line: tokens, cost, duration ---
   const resourceParts: string[] = [];
   if (stats.tokens > 0) {
-    resourceParts.push(`**${formatTokens(stats.tokens)}** tokens`);
+    // When prompt caching did real work, say so inline: cache reads are prompt
+    // tokens billed at the provider's discounted cached rate, and this is the
+    // only user-visible confirmation that caching is active for their model.
+    const cached = stats.cacheReadTokens > 0
+      ? ` (**${formatTokens(stats.cacheReadTokens)}** from cache)`
+      : '';
+    resourceParts.push(`**${formatTokens(stats.tokens)}** tokens${cached}`);
   }
   // 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