@lincoln504/pi-research 1.4.3 → 1.5.0

package/src/orchestration/quick-research-orchestrator.ts

@@ -19,6 +19,7 @@ import { getConfig, type Config } from '../config.ts';
 import { createResearcherSession } from './researcher.ts';
 import { ensureAssistantResponse, parseCitations } from '../utils/text-utils.ts';
 import { getMaxScrapeBatches, resolveExcludedTools } from '../constants.ts';
+import { resolveResearchModel, isPromptCachingActiveForModel } from '../core/llm/research-model-resolver.ts';
 import type { ResearchObserver } from '../core/interfaces/observer-interfaces.ts';
 import { HeadlessObserver, makeSafeObserver, type HeadlessObserverOptions } from './headless-observer.ts';
 import { getService, tryGetServiceContainerFromCtx } from '../core/service-registry.ts';
@@ -133,7 +134,15 @@ export class QuickResearchOrchestrator {
         }
 
         const researcherPromptTemplate = loadPrompt('researcher');
-        const maxScrapeBatches = getMaxScrapeBatches(this.config);
+        // Resolve the model here (same deterministic inputs createResearcherSession
+        // below will resolve again) purely to learn whether prompt caching will be
+        // active, so the batch count told to the model in the prompt below matches
+        // the limit ToolUsageTracker actually enforces — resolveResearchModel is a
+        // pure, cheap lookup over already-loaded registries, safe to call twice.
+        const cachingActiveForBudget = isPromptCachingActiveForModel(
+          resolveResearchModel({ modelRegistry: ctx.modelRegistry, config: this.config, hostModel: model, cwd: ctx.cwd })
+        );
+        const maxScrapeBatches = getMaxScrapeBatches(this.config, cachingActiveForBudget);
         const maxScrapeBatchesDisplay = maxScrapeBatches > 99 ? 'unlimited' : maxScrapeBatches.toString();
 
         const quickEvidenceSection =
@@ -162,19 +171,29 @@ export class QuickResearchOrchestrator {
         }
         evidenceLines.push(quickEvidenceSection);
 
+        // The system prompt carries only run-invariant instructions; the goal,
+        // knowledge-store results, evidence, and steering go in the initial USER
+        // message below. A byte-identical system prompt + tool set is the cacheable
+        // prefix providers key on, so back-to-back quick runs (and every follow-up
+        // turn within this session) reuse it via prompt-cache reads.
         const prompt = injectCurrentDate(researcherPromptTemplate, 'researcher')
-            // Function replacers: insert `$`-bearing dynamic content (scraped evidence,
-            // store descriptions, the user query) literally, not as a substitution pattern.
-            .replace('{{goal}}', () => query + steeringSection)
-            .replace('{{store_section}}', () => storeSection)
-            .replace('{{evidence_section}}', () => evidenceLines.join('\n\n'))
-            .replace('{{coordination_section}}', '')
             .replace('{{extra_tool_guidelines}}', '- `search`: Perform broad web searches (Round 1 only).')
             // Quick research has no research lead and no next round — see
             // RESEARCHER_DIGEST_SECTION. Its report IS the deliverable.
-            .replace('{{digest_section}}', '');
+            .replace('{{digest_section}}', '')
+            .trim();
 
-        logger.debug(`[QuickOrchestrator] System Prompt:\n${prompt}`);
+        // `$`-bearing dynamic content (the user query, store descriptions, steering)
+        // is plain string concatenation here — no String.replace substitution risk.
+        const userMessage = [
+          `Goal: ${query}`,
+          storeSection.trim(),
+          evidenceLines.join('\n\n').trim(),
+          steeringSection.trim(),
+          'Perform your research and submit your full report now.',
+        ].filter(Boolean).join('\n\n');
+
+        logger.debug(`[QuickOrchestrator] System Prompt:\n${prompt}\n\nUser Message:\n${userMessage}`);
 
         let lastSeenSearchCount = 0;
         const { session, resolvedModel } = await createResearcherSession({
@@ -287,7 +306,7 @@ export class QuickResearchOrchestrator {
           // whether the race resolves via session.prompt, timeout, or abort.
           let abortCleanup: (() => void) | undefined;
           try {
-            const promptPromise = session.prompt(query);
+            const promptPromise = session.prompt(userMessage);
             promptPromise.catch((err: Error) => logger.debug(`[QuickOrchestrator] Background session prompt rejection: ${err.message}`));
             await Promise.race([
               promptPromise,

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

@@ -34,6 +34,22 @@ const NO_SOURCES_NOTE =
 const UNVERIFIED_LINKS_NOTE =
   '_None of the links above could be verified: no page fetch succeeded this session and no citation could be matched to retrieved content. They may be inaccurate or invented — check each one before relying on it._';
 
+// Below this many verified sources, a completed report is WEAKLY grounded: it will
+// still read as a fully sourced document, but almost none of its claims can trace to
+// retrieved content — exactly the shape of a run where scrapes mostly failed (bot
+// blocks, resource starvation) or the topic had little real coverage, and the model
+// filled the gaps from its own weights. Observed in production: a depth-1 run whose
+// report cited ONE page shipped with no caveat and fabricated most of its specifics;
+// the calling agent had to detect the degradation itself. The note gives readers
+// (human or agent) the machine-visible signal that was missing.
+const WEAK_GROUNDING_MIN_SOURCES = 3;
+
+function weakGroundingNote(count: number): string {
+  return `_Grounding notice: only ${count} source${count === 1 ? '' : 's'} could be verified for this report. ` +
+    'Claims not attributable to the cited source' + (count === 1 ? '' : 's') +
+    ' above should be treated as unverified — cross-check anything load-bearing before relying on it._';
+}
+
 
 /**
  * Redact inline `https?://` tokens in synthesis prose whose URL was NOT retrieved
@@ -382,6 +398,16 @@ export class ResearchSynthesisService implements IService {
         // fabricated source can still reach the user; inline URLs also violate the
         // required format. Verified inline references (in `trustedUrls`) are kept.
         body = redactUnverifiedProseUrls(body, trustedUrls);
+        if (globalCitations.length < WEAK_GROUNDING_MIN_SOURCES) {
+          // The notice goes BEFORE the CITED LINKS header, never after it: anything
+          // trailing the last citation entry is absorbed into that entry's
+          // Description by parseCitations, and quick mode re-parses this exact
+          // string to build knowledge-store entries — a notice placed after the
+          // list polluted the stored description of the final source on precisely
+          // the degraded runs the notice exists to flag.
+          logger.warn(`[ResearchSynthesisService] Report is weakly grounded: only ${globalCitations.length} verified source(s) — appending grounding notice.`);
+          return `${body}\n\n${weakGroundingNote(globalCitations.length)}\n\n${verifiedLinksSection}`;
+        }
         return `${body}\n\n${verifiedLinksSection}`;
       }
       logger.warn('[ResearchSynthesisService] Synthesis missing CITED LINKS - appending verified version');
@@ -393,6 +419,12 @@ export class ResearchSynthesisService implements IService {
       const validIds = new Set(globalCitations.map((c) => c.id));
       let prose = rewriteCitationMarkers(synthesis.trim(), new Map(), (n) => !validIds.has(n));
       prose = redactUnverifiedProseUrls(prose, trustedUrls);
+      if (globalCitations.length < WEAK_GROUNDING_MIN_SOURCES) {
+        // Before the CITED LINKS header for the same parseCitations-absorption
+        // reason as the replace path above.
+        logger.warn(`[ResearchSynthesisService] Report is weakly grounded: only ${globalCitations.length} verified source(s) — appending grounding notice.`);
+        return `${prose}\n\n${weakGroundingNote(globalCitations.length)}\n\n${verifiedLinksSection}`;
+      }
       return `${prose}\n\n${verifiedLinksSection}`;
     }
 

package/src/orchestration/researcher-executor.ts

@@ -180,6 +180,20 @@ export async function runResearcher(options: RunResearcherOptions): Promise<void
   const researcherExecutionStartMs = Date.now();
   const deliveredSteeringIds = new Set<string>();
 
+  // The system prompt is deliberately invariant across researchers, rounds, AND
+  // retry attempts: everything per-researcher (goal, knowledge-store results,
+  // initial evidence, sibling coordination, steering) is delivered in the initial
+  // USER message instead. A byte-identical system prompt + tool set is the
+  // cacheable prefix providers key on, so every researcher after the first gets a
+  // prompt-cache read on that prefix rather than a fresh write. Built once, out
+  // of the retry loop, because nothing in it varies per attempt.
+  const researcherSystemPrompt = injectCurrentDate(researcherPromptTemplate, 'researcher')
+    .replace('{{extra_tool_guidelines}}', '')
+    // Function replacer so `$`-bearing content is inserted literally, not as a
+    // String.replace substitution pattern.
+    .replace('{{digest_section}}', () => RESEARCHER_DIGEST_SECTION)
+    .trim();
+
   for (let attempt = 1; attempt <= maxAttempts; attempt++) {
     // Launch boundary: never build a session for a run that is already cancelled
     // or fast-stopped. The abort sentinel keeps the wrapper's clean-cancel
@@ -221,30 +235,31 @@ export async function runResearcher(options: RunResearcherOptions): Promise<void
       }
     }
 
-    // Generate prompt for this attempt, incorporating ALL steering messages delivered so far
+    // Build this attempt's initial USER message: the researcher's assignment plus
+    // every per-researcher section that used to live in the system prompt (goal,
+    // knowledge-store results, initial evidence, sibling coordination), and ALL
+    // steering messages delivered so far. Rebuilt per attempt so a retry picks up
+    // steering that arrived between attempts; the system prompt above never changes.
     const allSteering = getSteeringMessages(sessionId);
     let steeringSection = '';
     if (allSteering.length > 0) {
-        steeringSection = '\n\n### ADDITIONAL USER GUIDANCE (Mandatory directional rules for your research)\n' +
+        steeringSection = '### ADDITIONAL USER GUIDANCE (Mandatory directional rules for your research)\n' +
             allSteering.map(m => {
                 deliveredSteeringIds.add(m.id);
                 return `- ${m.text}`;
             }).join('\n');
     }
 
-    const prompt = injectCurrentDate(researcherPromptTemplate, 'researcher')
-      // Function replacers so a `$`-bearing dynamic value (scraped evidence, store
-      // descriptions, or an LLM-authored goal containing $&, $$, $1, …) is inserted
-      // literally instead of being interpreted as a String.replace substitution pattern.
-      .replace('{{goal}}', () => researcherConfig.goal)
-      .replace('{{store_section}}', () => storeSection)
-      .replace('{{evidence_section}}', () => evidenceSection)
-      .replace('{{coordination_section}}', () => previousQueriesSection)
-      .replace('{{extra_tool_guidelines}}', '')
-      .replace('{{digest_section}}', () => RESEARCHER_DIGEST_SECTION)
-      .trim() + steeringSection;
+    const userMessage = [
+      `Topic: ${researcherConfig.name}\nGoal: ${researcherConfig.goal}`,
+      storeSection.trim(),
+      evidenceSection.trim(),
+      previousQueriesSection.trim(),
+      steeringSection,
+      'Perform your research and submit your full report now.',
+    ].filter(Boolean).join('\n\n');
 
-    logger.debug(`[ResearcherExecutor] Researcher ${id} attempt ${attempt} System Prompt:\n${prompt}`);
+    logger.debug(`[ResearcherExecutor] Researcher ${id} attempt ${attempt} System Prompt:\n${researcherSystemPrompt}\n\nUser Message:\n${userMessage}`);
 
     const workerExclude = ['search'];
     const mergedExclude = [...new Set([...workerExclude, ...(options.excludeTools || [])])];
@@ -275,7 +290,7 @@ export async function runResearcher(options: RunResearcherOptions): Promise<void
       cwd: ctx.cwd,
       ctxModel: model,
       modelRegistry: ctx.modelRegistry,
-      systemPrompt: prompt,
+      systemPrompt: researcherSystemPrompt,
       extensionCtx: ctx,
       excludeTools: mergedExclude,
       researcherId: id,
@@ -434,7 +449,7 @@ export async function runResearcher(options: RunResearcherOptions): Promise<void
 
       let abortCleanup: (() => void) | undefined;
       try {
-        const promptPromise = session.prompt(`Topic: ${researcherConfig.name}\nGoal: ${researcherConfig.goal}\n\nPerform your research and submit your full report now.`);
+        const promptPromise = session.prompt(userMessage);
         promptPromise.catch((err: Error) => logger.debug(`[ResearcherExecutor] Background session prompt rejection: ${err.message}`));
         await Promise.race([
           promptPromise,

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();
     }
   }
 }

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;
 }

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

@@ -29,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, getActiveResearchRunCount } 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';
@@ -252,19 +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 abort registration is
-        // still in place here (endResearchSession runs later in cleanup()), so a
-        // count of <= 1 means no other run is active. getActiveResearchRunCount
-        // (not getPiActivePanels) because headless runs never register a panel —
-        // a panel-based check here was always a no-op for headless callers.
-        try {
-          if (getActiveResearchRunCount(piSessionId) <= 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); }
         }
@@ -357,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 {
@@ -373,10 +385,9 @@ 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). Steering is NOT cleared here — teardownUi()
-              // already does that, gated on getActiveResearchRunCount so a finishing
-              // run doesn't wipe a concurrent sibling headless run's steering; an
-              // unconditional clear here bypassed that guard entirely.
+              // 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);
             };
             

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/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 {

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

package/src/utils/tool-usage-tracker.ts

@@ -195,12 +195,15 @@ export class ToolUsageTracker {
 }
 
 /**
- * Create default tool limits for a researcher
+ * Create default tool limits for a researcher.
+ *
+ * @param cachingActive - Whether prompt caching is active for this run's
+ * resolved model; see getMaxScrapeBatches in constants.ts.
  */
-export function createDefaultToolLimits(config?: Config): ToolLimits {
+export function createDefaultToolLimits(config?: Config, cachingActive = false): ToolLimits {
   return {
     gathering: getMaxGatheringCalls(config),
-    scrape: getMaxScrapeBatches(config),
+    scrape: getMaxScrapeBatches(config, cachingActive),
     search: 1,
     youtube_transcript: 1,
     grep: MAX_GREP_CALLS,