@lincoln504/pi-research 1.3.11 → 1.4.1

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

@@ -159,7 +159,17 @@ export class DeepResearchOrchestrator {
 
     const MAX_WAIT_RETRIES = 5;
     let waitRetryCount = 0;
-    let loopSynthesisPlan: ResearchPlan | null = null;
+    // Whether the ROUTER chose to finish inside the loop, as opposed to the loop ending
+    // because the round budget ran out. The router never carries the report: it is asked
+    // for a decision, is given no corpus to write from (it sees each report once, on the
+    // round it arrives, and digests thereafter), and any content it returns anyway is
+    // discarded in planning-service. So this only records which UI and observer events
+    // already fired, not a result to reuse. Final synthesis runs either way, below.
+    let routerChoseSynthesis = false;
+    // Highest round number handed to observer.onRoundStart. The final synthesis
+    // announces itself too, and it must not repeat or skip: `round_start` is an SDK
+    // event and a consumer counting rounds reads the gaps.
+    let lastAnnouncedRound = 0;
 
     try {
       while (this.currentRound < maxRounds) {
@@ -190,11 +200,36 @@ export class DeepResearchOrchestrator {
           }
         }
 
+        // The final iteration synthesizes; it never researches. Leave BEFORE announcing
+        // it, because announcing it is the whole problem: the log said `Round 2/2`, the
+        // observer fired onRoundStart (which arms the panel's deferred clear, consumed
+        // by a researcher start that never comes), the SDK emitted a `round_start`
+        // event, and a full infrastructure health check ran — 105 seconds of it on one
+        // measured run — for a round in which no researcher was ever dispatched. 92 of
+        // 93 capped runs in the retained logs announced a round that did nothing.
+        //
+        // This must sit AFTER the steering block above: a message consumed at the top of
+        // the final iteration raises maxRounds and legitimately turns this into a real
+        // research round. It must also not fire on round 1, which researches even when
+        // the budget is 1. The increment stays — the forced synthesis below is told
+        // which round it is synthesizing at.
+        if (this.currentRound > 1 && this.currentRound >= maxRounds) {
+          logger.log(`[DeepOrchestrator] Round cap (${maxRounds}) reached — skipping the evaluator and going straight to final synthesis ${this.elapsed()}`);
+          break;
+        }
+
         const roundLabel = this.currentRound > baseMaxRounds
           ? `Round ${this.currentRound}/${maxRounds} (extra, steering-driven, base=${baseMaxRounds})`
           : `Round ${this.currentRound}/${maxRounds}`;
         logger.log(`[DeepOrchestrator] ${roundLabel} ${this.elapsed()}`);
-        observer?.onRoundStart?.(this.currentRound);
+        // Guarded, because a 'wait' decision decrements the round and re-enters the loop
+        // to run the SAME round again. Announcing it each time emitted `round_start`
+        // 1, 2, 2, 3 — a duplicate rather than the gap the post-loop guard was added for,
+        // but the same broken contract for a consumer counting rounds.
+        if (this.currentRound > lastAnnouncedRound) {
+          observer?.onRoundStart?.(this.currentRound);
+          lastAnnouncedRound = this.currentRound;
+        }
 
         // Check infrastructure health (advisory: logs status, never aborts the run).
         await orchestrationService.checkHealth(this.currentRound, researchId, ctx);
@@ -217,17 +252,6 @@ export class DeepResearchOrchestrator {
                 excludeTools: this.options.excludeTools,
                 steeringMessages: steeringTexts,
             });
-        } else if (this.currentRound >= maxRounds) {
-            // Last iteration: the `plan.action === 'synthesize' || currentRound >=
-            // maxRounds` break below fires no matter what the evaluator decides, and
-            // the forced-synthesis path after the loop runs updatePlanForRound again
-            // with mustSynthesize. So on every capped run whose evaluator would have
-            // said `delegate` — the common case, since it is being cut off mid-plan —
-            // this call is a second full-context coordinator request whose result is
-            // discarded. Break straight to the forced synthesis: exactly one
-            // coordinator call either way, and the same outcome.
-            logger.log(`[DeepOrchestrator] Round cap (${maxRounds}) reached — skipping the evaluator and going straight to final synthesis ${this.elapsed()}`);
-            break;
         } else {
             const synthesisService = await getService<IResearchSynthesisService>(ServiceNames.RESEARCH_SYNTHESIS_SERVICE, ctx, container);
             observer?.onEvaluationStart?.(this.currentRound);
@@ -241,7 +265,12 @@ export class DeepResearchOrchestrator {
                 modelRegistry: ctx.modelRegistry,
                 cwd: ctx.cwd,
                 config: this.config,
+                // Both are used by routing, for different rounds: the bodies of the reports
+                // that arrived THIS round are sent in full, and every earlier researcher is
+                // represented by its digest alone. Passing reports also lets a caller-side
+                // digest miss fall back to deriving one from the body.
                 reports: synthesisService.getAllReports(researchId),
+                digests: synthesisService.getAllDigests(researchId),
                 previousPlan: planningService.getCurrentPlan(researchId),
                 totalResearchersPlanned: planningService.getTotalResearchersPlanned(researchId),
                 // Live, steering-extended budget — see maxRounds comment above. Without
@@ -271,7 +300,12 @@ export class DeepResearchOrchestrator {
         if (plan.action === 'synthesize' || this.currentRound >= maxRounds) {
             logger.log(`[DeepOrchestrator] Synthesis phase reached at Round ${this.currentRound} ${this.elapsed()}`);
             if (plan.action === 'synthesize') {
-                loopSynthesisPlan = plan;
+                // Only the ROUTER (round 2+) can reach this: generatePlan pins round 1 to
+                // 'delegate' so a coordinator can never end the run before any source is
+                // read. The router's decision ends the loop, but it has never held the
+                // whole corpus — only this round's reports and earlier digests — so the
+                // report itself is written by the terminal synthesis below.
+                routerChoseSynthesis = true;
                 observer?.onEvaluationDecision?.('synthesize', plan, this.currentRound);
             }
             break;
@@ -426,22 +460,71 @@ export class DeepResearchOrchestrator {
 
         // 5. Evaluation Phase
         observer?.onEvaluationProgress?.('evaluating');
+
+        // Counted at the END of a round that actually researched, which is what the
+        // run summary means by "rounds". The counter it used to read
+        // (`evaluator_runs_total`) lost its emit site in c90d7f37 and nothing noticed,
+        // because the only consumer gates on `> 1` — so a value permanently stuck at 0
+        // is indistinguishable from a single-round run, and the "N rounds" line has
+        // never rendered since.
+        metrics.increment('research_rounds_completed_total', 1, { mode: 'deep', complexity: String(complexity) });
+      }
+
+      // Final Synthesis — always its own call. Routing and synthesis are separate jobs:
+      // no router call ever holds the whole corpus (it reads each report on the single
+      // round it arrives, and digests after that), so none of them can produce the report
+      // and there is nothing from the loop to reuse. This costs one extra call on runs the
+      // router ends early, and in exchange removes a full re-send of the corpus from every
+      // round that preceded it.
+      //
+      // ZERO reports collected AND researchers actually failed — the run attempted
+      // research and produced nothing groundable. Checked BEFORE the synthesis call
+      // rather than after it: with every researcher failed (exactly the insufficient-
+      // credit class the researcher classifier exists for) the corpus is empty, so the
+      // call is billed over nothing and its result is then discarded by this very gate.
+      // The verdict does not depend on the synthesis text — it depends on whether there
+      // was any source material — so nothing is lost by asking first.
+      //
+      // Gated on failures, not merely on the absence of reports: a run cancelled before
+      // any researcher finished has no reports and no failures, and must not be reported
+      // as having produced nothing groundable.
+      const synthesisCheckService = await getService<IResearchSynthesisService>(ServiceNames.RESEARCH_SYNTHESIS_SERVICE, ctx, container);
+      const hasReports = synthesisCheckService.hasReports(researchId);
+      const failedIds = getFailedResearchers(this.options.sessionId, researchId);
+      if (!hasReports && failedIds.length > 0) {
+          const reasons = getResearcherFailureReasons(this.options.sessionId, researchId);
+          const causes = failedIds
+            .map((id) => `researcher ${id}: ${reasons[id] ?? 'no usable report'}`)
+            .join('; ');
+          throw new Error(
+            `Research produced no report — no source material was collected. Causes: ${causes}`
+          );
       }
 
-      // Final Synthesis — reuse the plan from the loop if the evaluator already
-      // decided to synthesize (avoids a second full LLM call). Only call the
-      // evaluator again when the loop ended because maxRounds was hit without
-      // the evaluator explicitly choosing to synthesize.
       logger.log(`[DeepOrchestrator] Final synthesis ${this.elapsed()}`);
-      // Only spin up the evaluation-phase UI when we still have to CALL the evaluator
-      // (loop ended on maxRounds). If the evaluator already chose to synthesize inside
-      // the loop, its eval slice was completed at that point (onEvaluationDecision) and
-      // its decision is final — re-adding a fresh 'eval' box here would leave a
-      // perpetually-"evaluating" slice that nothing ever completes, and re-emit
-      // start/progress after the decision. Symmetric with the decision guard below.
-      if (loopSynthesisPlan === null) {
-        observer?.onRoundStart?.(maxRounds + 1); // Progress indicator for synthesis
-        observer?.onEvaluationStart?.(maxRounds);
+      // Only spin up the evaluation-phase UI when the loop ended on maxRounds. If the
+      // router already chose to finish inside the loop, its eval slice was completed at
+      // that point (onEvaluationDecision) and its decision is final — re-adding a fresh
+      // 'eval' box here would leave a perpetually-"evaluating" slice that nothing ever
+      // completes, and re-emit start/progress after the decision. Symmetric with the
+      // decision guard below.
+      if (!routerChoseSynthesis) {
+        // The synthesis pass announces the round it is synthesizing AT, which is the
+        // one the loop stopped on — not `maxRounds + 1`, a number outside the budget
+        // every other event is expressed in. That was harmless while the loop
+        // announced the phantom final round (1,2,3 then a 4 nobody minded); with the
+        // phantom gone it left a hole: a 3-round run emitted round_start 1, 2, 4.
+        // Guarded so a one-round budget cannot announce the same round twice.
+        if (this.currentRound > lastAnnouncedRound) {
+          observer?.onRoundStart?.(this.currentRound);
+          lastAnnouncedRound = this.currentRound;
+        }
+        // The round this synthesis actually happens at, not the budget. They coincide on
+        // the round-cap exit but not on the wait-exhaustion one, which breaks out early —
+        // that path announced `evaluation_start` for a round no `round_start` had ever
+        // named, and the round it really stopped on was left with an evaluation slice
+        // that never received a decision.
+        observer?.onEvaluationStart?.(this.currentRound);
         observer?.onEvaluationProgress?.('evaluating');
       }
 
@@ -451,81 +534,52 @@ export class DeepResearchOrchestrator {
       // toast and then be destroyed at teardown. With the flag off first (this and
       // the consume run synchronously — no interleaving window), any later steer
       // takes the input handler's fall-through path (forwarded to pi, accurate
-      // toast). On the evaluator-chose-synthesize path this is idempotent: the
+      // toast). On the router-chose-synthesis path this is idempotent: the
       // observer already flipped the flag in onEvaluationDecision('synthesize').
       // NOTE: this must also come after the onEvaluationStart above, which re-sets
       // the flag to true (correct for in-loop evaluations, wrong for this final one).
       observer?.onSynthesisStart?.();
 
       // One final check for new steering messages before synthesis. Done for BOTH
-      // exit paths: a message arriving after the evaluator chose 'synthesize' (the
-      // loopSynthesisPlan path) was previously never consumed nor appended — fully
-      // dropped. Consuming here marks it active so appendSteeringGuidance includes it.
+      // exit paths: a message arriving after the router chose to finish was previously
+      // never consumed nor appended — fully dropped. Consuming here marks it active so
+      // appendSteeringGuidance includes it.
       consumeQueuedMessages(this.options.sessionId);
       const finalSteeringTexts = getSteeringMessages(this.options.sessionId).map(m => m.text);
 
-      let finalReport: ResearchPlan;
-      if (loopSynthesisPlan !== null) {
-          finalReport = loopSynthesisPlan;
-      } else {
-          const synthesisServiceFinal = await getService<IResearchSynthesisService>(ServiceNames.RESEARCH_SYNTHESIS_SERVICE, ctx, container);
-          finalReport = await planningService.updatePlanForRound({
-              sessionId: researchId,
-              query: query,
-              complexity,
-              round: maxRounds,
-              model: coordinatorModel,
-              modelRegistry: ctx.modelRegistry,
-              cwd: ctx.cwd,
-              config: this.config,
-              reports: synthesisServiceFinal.getAllReports(researchId),
-              previousPlan: planningService.getCurrentPlan(researchId),
-              totalResearchersPlanned: planningService.getTotalResearchersPlanned(researchId),
-              mustSynthesize: true,
-              // Live, steering-extended budget — see the in-loop call above.
-              maxRounds,
-              signal,
-              observer,
-              excludeTools: this.options.excludeTools,
-              steeringMessages: finalSteeringTexts,
-          });
-      }
+      const synthesisServiceFinal = await getService<IResearchSynthesisService>(ServiceNames.RESEARCH_SYNTHESIS_SERVICE, ctx, container);
+      const finalReport: ResearchPlan = await planningService.updatePlanForRound({
+          sessionId: researchId,
+          query: query,
+          complexity,
+          round: this.currentRound,
+          model: coordinatorModel,
+          modelRegistry: ctx.modelRegistry,
+          cwd: ctx.cwd,
+          config: this.config,
+          reports: synthesisServiceFinal.getAllReports(researchId),
+          previousPlan: planningService.getCurrentPlan(researchId),
+          totalResearchersPlanned: planningService.getTotalResearchersPlanned(researchId),
+          mustSynthesize: true,
+          // Live, steering-extended budget — see the in-loop call above.
+          maxRounds,
+          signal,
+          observer,
+          excludeTools: this.options.excludeTools,
+          steeringMessages: finalSteeringTexts,
+      });
 
       // Only emit the synthesis decision here for the FORCED-synthesis path. When the
-      // evaluator itself chose to synthesize inside the loop (loopSynthesisPlan set),
-      // onEvaluationDecision('synthesize', ...) was already fired at that point; emitting
-      // again would double-count synthesis for observers (e.g. the TUI progress bar).
-      if (loopSynthesisPlan === null) {
-          observer?.onEvaluationDecision?.('synthesize', finalReport, maxRounds);
+      // router chose to finish inside the loop, onEvaluationDecision('synthesize', ...)
+      // was already fired at that point; emitting again would double-count synthesis for
+      // observers (e.g. the TUI progress bar).
+      if (!routerChoseSynthesis) {
+          // Same round the matching onEvaluationStart above used — see there.
+          observer?.onEvaluationDecision?.('synthesize', finalReport, this.currentRound);
       }
 
       let result = finalReport.content || '';
 
-      // ZERO reports collected AND researchers actually failed — the run attempted
-      // research and produced nothing groundable. This gate is deliberately
-      // independent of the synthesis text: with the default single-researcher plan
-      // the fast-stop threshold (MAX_FAILED_RESEARCHERS = 2) never trips, so a lone
-      // researcher that exhausts its retries (e.g. a provider rate limit) reaches
-      // synthesis with no source material. Whether the LLM then returns an empty
-      // string OR chatty refusal prose ("no information was found"), that is a
-      // FAILED run: throw, and surface the recorded root causes so the user sees
-      // the 429/model error, not a shrug (and never a source-free report shipped
-      // as success). The failed-researcher condition keeps the designed
-      // immediate-synthesis path intact: a coordinator that chose to answer
-      // directly (no delegation, no failures) is not a failed run.
-      const synthesisCheckService = await getService<IResearchSynthesisService>(ServiceNames.RESEARCH_SYNTHESIS_SERVICE, ctx, container);
-      const hasReports = synthesisCheckService.hasReports(researchId);
-      const failedIds = getFailedResearchers(this.options.sessionId, researchId);
-      if (!hasReports && failedIds.length > 0) {
-          const reasons = getResearcherFailureReasons(this.options.sessionId, researchId);
-          const causes = failedIds
-            .map((id) => `researcher ${id}: ${reasons[id] ?? 'no usable report'}`)
-            .join('; ');
-          throw new Error(
-            `Research produced no report — no source material was collected. Causes: ${causes}`
-          );
-      }
-
       if (!result.trim()) {
           if (hasReports) {
               // Content is empty but reports exist — build a fallback synthesis.

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

@@ -169,7 +169,10 @@ export class QuickResearchOrchestrator {
             .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).');
+            .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}}', '');
 
         logger.debug(`[QuickOrchestrator] System Prompt:\n${prompt}`);
 
@@ -325,7 +328,13 @@ export class QuickResearchOrchestrator {
           // Store report in synthesis service so citations can be verified/processed
           const synthesisService = await getService<IResearchSynthesisService>(ServiceNames.RESEARCH_SYNTHESIS_SERVICE, ctx, container);
           synthesisService.storeReport(this.options.researchId, 'quick', result);
-          
+          // Continue from the STORED body. Quick research uses the same researcher prompt as
+          // a deep run, so its report opens with a COVERAGE DIGEST block — routing metadata
+          // for a lead that does not exist in this mode. Unlike a deep run, this text IS the
+          // deliverable and goes straight to the user, so reading it back is what keeps the
+          // digest out of the delivered document.
+          result = synthesisService.getReport(this.options.researchId, 'quick') ?? result;
+
           // Ensure CITED LINKS section is accurate and consistent
           result = synthesisService.ensureCitedLinks(this.options.researchId, result);
 

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

@@ -14,7 +14,7 @@ import type { Model } from '@earendil-works/pi-ai';
 import { resolveResearchModel } from '../core/llm/research-model-resolver.ts';
 import type { QueryResultWithError } from '../web-research/types.ts';
 import type { RunResearchersOptions } from './orchestration-types.ts';
-import { RESEARCHER_LAUNCH_DELAY_MS, resolveExcludedTools } from '../constants.ts';
+import { RESEARCHER_LAUNCH_DELAY_MS, RESEARCH_TOOL_NAMES, resolveExcludedTools } from '../constants.ts';
 import { search } from '../web-research/search.ts';
 import { parseCitations } from '../utils/text-utils.ts';
 import { logger, resetLogger } from '../logger.ts';
@@ -98,6 +98,27 @@ export class ResearchOrchestrationService implements IResearchOrchestration {
     const configDisabledTools = researchConfig.DISABLED_TOOLS
       ? researchConfig.DISABLED_TOOLS.split(',').map((s) => s.trim()).filter(Boolean)
       : [];
+    // Unknown names are a SILENT no-op downstream (the merge is a blind Set union),
+    // so a typo leaves the tool enabled for a whole billed run while the user
+    // believes it is off. `--exclude-tools` fails fast on this in the CLI parser;
+    // its two siblings — the SDK's `excludeTools` option and
+    // PI_RESEARCH_DISABLED_TOOLS — reach the same union with no check at all, and
+    // RESEARCH_TOOL_NAMES already documents itself as the vocabulary all THREE
+    // accept. Warn rather than throw here: this chokepoint is mid-run and serves a
+    // library API and an ambient env var, where aborting a legitimate request over
+    // one unrecognized name is the wrong trade — the CLI keeps its fail-fast.
+    for (const [surface, names] of [
+      ['excludeTools', excludeTools ?? []],
+      ['PI_RESEARCH_DISABLED_TOOLS', configDisabledTools],
+    ] as const) {
+      const unknown = names.filter((t) => !RESEARCH_TOOL_NAMES.includes(t));
+      if (unknown.length > 0) {
+        logger.warn(
+          `[ResearchOrchestrationService] ${surface}: ignoring unknown tool name${unknown.length === 1 ? '' : 's'} ` +
+          `${unknown.map((t) => `"${t}"`).join(', ')} — these exclude nothing. Valid names: ${RESEARCH_TOOL_NAMES.join(', ')}.`
+        );
+      }
+    }
     const mergedExcludeTools = resolveExcludedTools(excludeTools, configDisabledTools);
 
     // Resolve model using centralized priority logic
@@ -643,6 +664,14 @@ export class ResearchOrchestrationService implements IResearchOrchestration {
    * @param ctx - Optional extension context for container isolation
    */
   async checkHealth(round: number, _researchId?: string, ctx?: any): Promise<void> {
+    // Round 1 is skipped because there is nothing to diagnose yet — the pool was
+    // built moments earlier and no work has run through it. A consequence worth
+    // stating: a complexity-1 run has exactly ONE research round, so it now never
+    // runs this at all. That is correct rather than a gap. It used to run at the
+    // phantom final round, which dispatched no researchers and on one measured run
+    // spent 105 seconds probing infrastructure that the synthesis pass ahead of it
+    // does not use. This check is advisory logging; a quick run loses nothing but
+    // that cost.
     if (round <= 1) return;
 
     try {

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

@@ -11,6 +11,7 @@
 
 import { parseCitations } from '../utils/text-utils.ts';
 import { normalizeCitations, formatCitedLinks, rewriteCitationMarkers, type GlobalCitation } from '../utils/citation-utils.ts';
+import { splitCoverageDigest, deriveCoverageDigest } from '../utils/coverage-digest.ts';
 import { lastCitedLinksHeaderIndex, lastCitedLinksHeader } from '../utils/text-utils.ts';
 import { getScrapedLinks, isTranscribedLink, normalizeUrl } from '../utils/shared-links.ts';
 import { stripTrailingLlmPunctuation } from '../utils/url-utils.ts';
@@ -77,6 +78,12 @@ export class ResearchSynthesisService implements IService {
 
   // Map of sessionId -> Map<reportId, reportContent>
   private sessions = new Map<string, Map<string, string>>();
+  // Map of sessionId -> Map<reportId, coverageDigest>, split off the report at store time.
+  // Kept parallel to `sessions` rather than folded into it so every existing consumer of a
+  // report keeps receiving a plain string body. Lifecycle is mirrored everywhere `sessions`
+  // is mutated (store, LRU evict, clear, dispose) — a digest map that outlives its reports
+  // would hand the router coverage for findings the synthesizer no longer has.
+  private digests = new Map<string, Map<string, string>>();
   // Cap to prevent unbounded growth from orphaned sessions during long-lived Pi
   // sessions. Generous because each session map is small and the normal path clears
   // reports via cleanupResearchServices on run completion — this is only a backstop
@@ -103,6 +110,7 @@ export class ResearchSynthesisService implements IService {
       if (oldestKey !== undefined) {
         logger.warn(`[ResearchSynthesisService] Session limit (${ResearchSynthesisService.MAX_SESSIONS}) reached, evicting least-recently-used: ${oldestKey}`);
         this.sessions.delete(oldestKey);
+        this.digests.delete(oldestKey);
       }
     }
     reports = new Map<string, string>();
@@ -136,7 +144,47 @@ export class ResearchSynthesisService implements IService {
    * @param report - The researcher's report content
    */
   storeReport(sessionId: string, id: string, report: string): void {
-    this.getSessionReports(sessionId).set(id, report);
+    // Split the coverage digest off the head of the report here, at the single point every
+    // report enters the system. Downstream consumers — citation normalization, the
+    // synthesis corpus, the fallback synthesis, the knowledge store — then see a body with
+    // no routing metadata in it, unchanged from before this protocol existed.
+    const { digest, body } = splitCoverageDigest(report);
+    this.getSessionReports(sessionId).set(id, body);
+
+    // Storing the same id twice REPLACES the report, so it must replace the digest too.
+    // Setting only when the new report carries one would leave the previous report's
+    // coverage claims attached to a body that no longer supports them — the router would
+    // then route on findings that were superseded. Delete on absence so the derived digest
+    // (which reads the current body) takes over instead.
+    let sessionDigests = this.digests.get(sessionId);
+    if (digest) {
+      if (!sessionDigests) {
+        sessionDigests = new Map<string, string>();
+        this.digests.set(sessionId, sessionDigests);
+      }
+      sessionDigests.set(id, digest);
+    } else if (sessionDigests) {
+      sessionDigests.delete(id);
+      if (sessionDigests.size === 0) this.digests.delete(sessionId);
+    }
+  }
+
+  /**
+   * Coverage digests for every stored report, in report order.
+   *
+   * A report whose researcher emitted no digest gets one derived from its body, so the
+   * router sees an entry for every researcher that ran. The alternative — omitting it —
+   * reads to the router as "that researcher produced nothing", which is both wrong and
+   * the more dangerous error: it argues for re-delegating work already done.
+   */
+  getAllDigests(sessionId: string): Map<string, string> {
+    const reports = this.peekSessionReports(sessionId);
+    const stored = this.digests.get(sessionId);
+    const out = new Map<string, string>();
+    for (const [id, body] of reports.entries()) {
+      out.set(id, stored?.get(id) ?? deriveCoverageDigest(body));
+    }
+    return out;
   }
 
   /**
@@ -187,8 +235,10 @@ export class ResearchSynthesisService implements IService {
   clearReports(sessionId?: string): void {
     if (sessionId) {
       this.sessions.delete(sessionId);
+      this.digests.delete(sessionId);
     } else {
       this.sessions.clear();
+      this.digests.clear();
     }
   }
 
@@ -442,6 +492,7 @@ export class ResearchSynthesisService implements IService {
    */
   reset(): void {
     this.sessions.clear();
+    this.digests.clear();
   }
 
   async initialize(): Promise<void> {
@@ -461,6 +512,7 @@ export class ResearchSynthesisService implements IService {
     this.lifecycle = ServiceLifecycle.DISPOSING;
     logger.debug('[ResearchSynthesisService] Disposing...');
     this.sessions.clear();
+    this.digests.clear();
     this.lifecycle = ServiceLifecycle.DISPOSED;
     logger.debug('[ResearchSynthesisService] Disposed');
   }

package/src/orchestration/researcher-executor.ts

@@ -23,6 +23,42 @@ import { recordResearcherFailure, getSteeringMessages, shouldStopResearch } from
 import { isAbortSentinel, boundSessionAbort } from './abort-utils.ts';
 import type { RunResearcherOptions } from './orchestration-types.ts';
 import { search } from '../web-research/search.ts';
+import { RESEARCHER_DIGEST_SECTION } from '../utils/coverage-digest.ts';
+
+/**
+ * Failures a retry cannot fix, because the next attempt sends the same request to
+ * the same account and gets the same answer.
+ *
+ * Deliberately narrow. The retry loop is otherwise unclassified and that is mostly
+ * FINE — the log history says so. Across 53 days the loop retried 126 attempts:
+ * "produced no text output" recovered 26/26; a provider rejecting
+ * `reasoning_effort: 'none'` recovered ~18/19, because OpenRouter routes the same
+ * model to different upstream providers per request and only some reject it;
+ * token-limit truncation recovered ~16/17. Classifying any of those as permanent
+ * would break runs that currently succeed.
+ *
+ * Insufficient credits is the one class with no recoveries at all: 30 retried
+ * attempts, every one belonging to an episode that went on to exhaust, 0 of 10
+ * recovered. Those ten cost five runs their entire output — searches already paid
+ * for, 70 results collected and discarded, and a synthesis call billed over an
+ * empty corpus before the run threw. The account balance does not change in the
+ * two seconds between attempts.
+ *
+ * Note what this does NOT cover: a researcher timeout retries and recovers ~88% of
+ * the time, so it stays retriable even though three attempts at a 15-minute budget
+ * cost 45 minutes of wall clock. That cost is real and worth addressing, but by
+ * bounding total retry time rather than by refusing the retry that usually works.
+ */
+export function isUnretriableResearcherError(error: unknown): boolean {
+  const message = (error instanceof Error ? error.message : String(error)).toLowerCase();
+  // Matched on the provider's wording rather than a bare "402": a status code can
+  // appear inside an unrelated payload (a token count, a URL, a quoted response
+  // body), and this gate ends a researcher's run — it must not fire on a
+  // coincidence. Same reasoning as isTransientSynthesisError's boundary anchoring.
+  return message.includes('requires more credits')
+    || message.includes('insufficient credits')
+    || message.includes('insufficient_quota');
+}
 
 /**
  * Run a single researcher with retries
@@ -205,6 +241,7 @@ export async function runResearcher(options: RunResearcherOptions): Promise<void
       .replace('{{evidence_section}}', () => evidenceSection)
       .replace('{{coordination_section}}', () => previousQueriesSection)
       .replace('{{extra_tool_guidelines}}', '')
+      .replace('{{digest_section}}', () => RESEARCHER_DIGEST_SECTION)
       .trim() + steeringSection;
 
     logger.debug(`[ResearcherExecutor] Researcher ${id} attempt ${attempt} System Prompt:\n${prompt}`);
@@ -453,7 +490,11 @@ export async function runResearcher(options: RunResearcherOptions): Promise<void
       const synthesisService = await getService<IResearchSynthesisService>(ServiceNames.RESEARCH_SYNTHESIS_SERVICE, ctx, container);
       synthesisService.storeReport(researchId, `${round}.${id}`, responseText);
 
-      observer?.onResearcherComplete?.(id, responseText);
+      // Emit what was STORED, not what the model returned: storeReport splits the coverage
+      // digest off the head of the report, and the SDK's `researcher_complete` event should
+      // carry the report a consumer would get from the run, not the routing metadata that
+      // was stripped out of it.
+      observer?.onResearcherComplete?.(id, synthesisService.getReport(researchId, `${round}.${id}`) ?? responseText);
       return;
     } catch (err) {
       lastError = err;
@@ -484,7 +525,8 @@ export async function runResearcher(options: RunResearcherOptions): Promise<void
           const synthesisService = await getService<IResearchSynthesisService>(ServiceNames.RESEARCH_SYNTHESIS_SERVICE, ctx, container);
           synthesisService.storeReport(researchId, `${round}.${id}`, partialResponse + '\n\n---\n*WARNING: This report was truncated due to a timeout/error. Content may be incomplete.*');
           logger.log(`[ResearcherExecutor] Researcher ${id} salvaged partial content (${partialResponse.length} chars) after error: ${errMsg}`);
-          observer?.onResearcherComplete?.(id, partialResponse);
+          // As on the success path: emit the stored body, with the digest already split off.
+          observer?.onResearcherComplete?.(id, synthesisService.getReport(researchId, `${round}.${id}`) ?? partialResponse);
           return;
         }
       } catch (salvageErr) {
@@ -508,6 +550,15 @@ export async function runResearcher(options: RunResearcherOptions): Promise<void
         break; // Break out of the attempt loop
       }
 
+      // A failure the account cannot retry its way out of. Spending the remaining
+      // attempts changes nothing except how long the user waits for the same answer,
+      // and it buries the real cause under three duplicate warnings.
+      if (isUnretriableResearcherError(err)) {
+        logger.error(`[ResearcherExecutor] Researcher ${id} failed with an unretriable provider error, not retrying: ${errMsg}`);
+        metrics.increment('researcher_unretriable_total', 1, { mode: 'deep', complexity: String(complexity) });
+        break;
+      }
+
       if (attempt < maxAttempts) {
         logger.warn(`[ResearcherExecutor] Researcher ${id} attempt ${attempt} failed: ${errMsg}; will retry`);
       } else {

package/src/orchestration/researcher.ts

@@ -109,10 +109,23 @@ export async function createResearcherSession(options: CreateResearcherSessionOp
           if (usage && typeof usage.tokens === 'number') return usage.tokens;
         }
         
-        // Fallback to cumulative session usage
+        // Fallback to cumulative session usage. Cache-read and cache-write tokens are
+        // part of the prompt and occupy the context window exactly like uncached input;
+        // the providers simply bill them differently. pi-ai reports them as SEPARATE
+        // fields with `input` already net of both (openai-completions computes
+        // `input = prompt_tokens - cacheRead - cacheWrite`), so summing input+output
+        // alone under-reports the real context by the entire cached prefix. On a
+        // provider where caching works that is most of the prompt, which would leave
+        // the tool layer's context gate (it divides this by contextWindowSize) reading
+        // near-empty on a session that is nearly full.
         if (typeof (sessionRef.session as any).getUsage === 'function') {
           const usage = (sessionRef.session as any).getUsage();
-          return (usage.input || 0) + (usage.output || 0);
+          return (
+            (usage.input || 0) +
+            (usage.output || 0) +
+            (usage.cacheRead || 0) +
+            (usage.cacheWrite || 0)
+          );
         }
         
         return 0;

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

@@ -61,7 +61,7 @@ The `research` tool retrieves from the internet. Do NOT use it when the answer c
 - `depth: 3` — **ABSOLUTELY NEVER without explicit user request.** The user MUST use trigger words like "ultra", "exhaustive", "comprehensive deep-dive", or "maximum research". If the user does not explicitly request this level, use depth 1 or depth 2.
 
 **How depth works internally:**
-- `depth: 1-3` — AI-orchestrated: coordinator plans a team, researchers execute, evaluator decides whether to continue deeper. Team size and number of rounds scale with complexity. The coordinator and evaluator dynamically determine how many researchers are needed each round — it's not a fixed number.
+- `depth: 1-3` — AI-orchestrated: coordinator plans a team, researchers execute, a research lead decides whether to continue deeper and writes the final report. Team size and number of rounds scale with complexity. The coordinator and the lead dynamically determine how many researchers are needed each round — it's not a fixed number.
 
 **Max siblings per round by depth:**
 - `depth: 1` — up to {{max_team_size_l1}} researchers per round

package/src/prompts/researcher.md

@@ -73,6 +73,7 @@ Write your report immediately after scraping is complete, or as soon as a tool r
 
 ## Report Format
 
+{{digest_section}}
 Use [N] inline citations throughout. Write in plain prose — no markdown headings, no bullet points, no bold or italic text. Use clear paragraphs separated by blank lines. The full CITED LINKS list goes at the very end.
 
 [Topic Title]

package/src/prompts/system-coordinator.md

@@ -36,7 +36,7 @@ Before splitting the query into researchers, pin down its scope — exactly what
 
 1. **Plan ONLY Round 1**: Split the query into distinct sub-topics, all inside the scope above, each assigned to a researcher. **Do NOT plan multiple rounds in advance** — additional rounds are only delegated reactively when Round 1 findings reveal gaps.
 2. **Assign Goals**: Each researcher gets a focused goal covering a specific angle or time period.
-3. **Temporal Awareness**: Lead with the current month and year shown above. Generate time-sensitive queries using that exact month and year (e.g., append the current year and, where relevant, the current month; "latest", "current status"). Never anchor queries to an older year (e.g. 2024 or 2025) unless the user explicitly asks about the past. Research MUST be grounded in the present month and year.
+3. **Temporal Awareness**: Lead with the current month and year shown above. Generate time-sensitive queries using that exact month and year (e.g., append the current year and, where relevant, the current month; "latest", "current status"). Never anchor queries to an older year than the one shown above unless the user explicitly asks about the past. Research MUST be grounded in the present month and year.
 4. **Query Planning**: For EACH researcher, generate targeted, specific queries within the budget. Fill the budget when the topic is broad enough to warrant it, but don't pad queries for a narrow topic. Each round is planned independently — make Round 1 count.
 5. **YouTube Discovery**: For roughly **one in {{youtube_query_every_n}}** of each researcher's queries, append the word `youtube` to the query text (e.g. `"<topic> explained youtube"`). DuckDuckGo rarely surfaces YouTube on its own, and YouTube links let researchers read video transcripts. Skip this only when the topic is clearly unsuited to video (e.g. a single numeric lookup).
 6. **Seed Search Burst**: All queries across all researchers are combined into a single pre-search pass that seeds the global link pool.