@lincoln504/pi-research 1.3.12 → 1.4.3

package/src/core/planning-service.ts

@@ -21,12 +21,16 @@ import { injectCurrentDate } from './llm/inject-date.ts';
 import { loadPrompt } from './llm/prompts.ts';
 import { recordLlmUsage } from '../utils/llm-usage.ts';
 import { normalizeCitations } from '../utils/citation-utils.ts';
+import { lastCitedLinksHeader } from '../utils/text-utils.ts';
 import { repairJsonWithLlm } from './llm/agentic-repair.ts';
 import { buildSafeOptions, validateAndExtractText } from './llm/llm-utils.ts';
 import { safeGetApiKeyAndHeaders } from './llm/model-registry-factory.ts';
 import { withTimeout } from './llm/llm-timeout.ts';
 import { retryWithBackoff, isTransientError } from '../web-research/retry-utils.ts';
-import { getConfig } from '../config.ts';
+import { getConfig, type Config } from '../config.ts';
+import type { Model } from '@earendil-works/pi-ai';
+import { DEFAULT_MODEL_CONTEXT_WINDOW } from '../constants.ts';
+import { deriveCoverageDigest, formatDigestsForRouter } from '../utils/coverage-digest.ts';
 import {
   PlanningResponseSchemaAsTSchema,
   EvaluationResponseSchemaAsTSchema,
@@ -54,6 +58,120 @@ const LLM_MAX_RETRIES = 2;
 const LLM_RETRY_INITIAL_DELAY_MS = 1000;
 const LLM_RETRY_MAX_DELAY_MS = 8000;
 
+/**
+ * Output ceiling for a ROUTING call.
+ *
+ * The router emits a decision, never a report — at worst a delegate plan of
+ * `maxTeamSize` researchers each carrying `queryBudget` queries, which is a couple of
+ * thousand tokens at Level 3. It used to share the synthesis budget because the same call
+ * could return the final report; under the split protocol it cannot, so a ceiling this
+ * far above the real ceiling is only there to leave room for a model that reasons before
+ * answering. Still clamped to the model by buildSafeOptions.
+ */
+const ROUTER_MAX_TOKENS = 8192;
+
+/** Rough bytes-per-token used to budget the synthesis corpus. Deliberately conservative. */
+const CHARS_PER_TOKEN = 4;
+
+/**
+ * Tokens held back from the context window, on top of the configured output ceiling, to
+ * cover the system prompt and the slack between a chars/4 estimate and a real tokenizer on
+ * prose that is heavy with URLs and citation markers.
+ *
+ * This does NOT cover the global source list or the run context (previous-queries section):
+ * both ride along on every partial and merge pass verbatim, but neither has a fixed size —
+ * the source list grows with every citation the run collected (each with a free-text
+ * description) and the run context grows with the run's entire query history, uncapped. A
+ * fixed reserve here cannot bound either, so `synthesisCorpusBudgetChars` takes their actual
+ * character length as a separate argument and subtracts it directly, at the point where it
+ * is already known (see synthesizeCorpus).
+ */
+const SYNTHESIS_OVERHEAD_TOKENS = 8000;
+
+/**
+ * Floor on the corpus budget. Below this, partitioning produces so many partial passes
+ * that the reduce costs more than the overflow it avoids — better to send one oversized
+ * request and let the provider's own error surface than to fan out indefinitely.
+ */
+const MIN_SYNTHESIS_CORPUS_CHARS = 40_000;
+
+/**
+ * How many reduce passes the synthesizer may run before it merges whatever it has.
+ * A run whose corpus needs more than this has grown far past anything the round budget
+ * can produce; the bound exists so a pathological input cannot spin.
+ */
+const MAX_SYNTHESIS_REDUCE_PASSES = 3;
+
+/**
+ * Floor on a partial pass's output ceiling. A wide fan-out divides the corpus budget many
+ * ways; without a floor a 12-partition reduce would allot each partial too few tokens to
+ * hold its slice of the findings, and "exhaustive synthesis" would quietly become
+ * summarisation. When the floor binds, the partials may not fit in one pass — that is what
+ * the remaining passes are for.
+ */
+const MIN_PARTIAL_SYNTHESIS_TOKENS = 4096;
+
+/**
+ * Characters of corpus a single synthesis request may carry for `model`.
+ *
+ * The final synthesis is the one call whose input grows without bound: it carries every
+ * report the run collected. Nothing upstream caps it — there is no per-report budget and
+ * no cap on report count — so on a deep, steering-extended run it can exceed the model's
+ * context window, and the failure is expensive and late: the provider rejects the request
+ * after the entire run has been paid for, and the orchestrator degrades to a mechanical
+ * concatenation of the raw reports. Budgeting here converts that cliff into a bounded
+ * two-pass reduce.
+ *
+ * `extraOverheadChars` is the actual character length of the OTHER unbounded things that
+ * ride along on every partial and merge pass — the global source list and the run context —
+ * measured by the caller before partitioning, since both are already built by then. Without
+ * this, a run with a large citation list or a long query history can overflow the window
+ * through an input the budget never counted, which is exactly the failure class this
+ * function exists to prevent for the report corpus itself.
+ */
+export function synthesisCorpusBudgetChars(
+  model: { contextWindow?: number },
+  outputTokens: number,
+  extraOverheadChars = 0,
+): number {
+  const window = model.contextWindow ?? DEFAULT_MODEL_CONTEXT_WINDOW;
+  const usable = window - outputTokens - SYNTHESIS_OVERHEAD_TOKENS - extraOverheadChars / CHARS_PER_TOKEN;
+  return Math.max(MIN_SYNTHESIS_CORPUS_CHARS, usable * CHARS_PER_TOKEN);
+}
+
+/**
+ * Greedily group corpus entries into runs that each fit `budgetChars`, preserving order.
+ *
+ * Order is preserved because global citation ids are assigned by first appearance across
+ * the reports in this same order; keeping partitions contiguous keeps each partial pass
+ * looking at a coherent, mostly-self-consistent slice of the numbering rather than an
+ * arbitrary scatter of it.
+ *
+ * A single entry larger than the whole budget gets a partition to itself and is truncated
+ * by the caller — at that point there is no partitioning left to do.
+ */
+export function partitionCorpus<T>(
+  entries: Array<[string, T]>,
+  sizeOf: (entry: [string, T]) => number,
+  budgetChars: number,
+): Array<Array<[string, T]>> {
+  const partitions: Array<Array<[string, T]>> = [];
+  let current: Array<[string, T]> = [];
+  let currentSize = 0;
+  for (const entry of entries) {
+    const size = sizeOf(entry);
+    if (current.length > 0 && currentSize + size > budgetChars) {
+      partitions.push(current);
+      current = [];
+      currentSize = 0;
+    }
+    current.push(entry);
+    currentSize += size;
+  }
+  if (current.length > 0) partitions.push(current);
+  return partitions;
+}
+
 /**
  * Whether a failed coordinator/evaluator LLM call should be RETRIED. Retries only fast,
  * transient transport failures: an undici mid-stream abort ("terminated"), a dropped socket,
@@ -214,8 +332,8 @@ export class PlanningService implements IPlanningService {
     return _getComplexityGuidance(complexity, maxTeamSize, queryBudget);
   }
 
-  getEvaluatorComplexityGuidance(complexity: 1 | 2 | 3): string {
-    return _getEvaluatorComplexityGuidance(complexity);
+  getEvaluatorComplexityGuidance(complexity: 1 | 2 | 3, researchRounds: number): string {
+    return _getEvaluatorComplexityGuidance(complexity, researchRounds);
   }
 
   getRoundPhaseGuidance(currentRound: number, maxRounds: number, complexity: 1 | 2 | 3, maxTeamSize: number): string {
@@ -314,7 +432,8 @@ export class PlanningService implements IPlanningService {
             }, buildSafeOptions(model, {
               apiKey: authResult.apiKey || '',
               headers: authResult.headers,
-              signal
+              signal,
+              sessionId,
             }, config.PLANNING_MAX_TOKENS, config.LLM_THINKING_LEVEL)),
             llmTimeout, 'coordinator-generatePlan',
           );
@@ -350,6 +469,7 @@ export class PlanningService implements IPlanningService {
                 context: `Research planning for: ${query}`,
                 serviceName: 'PlanningService',
                 signal,
+                sessionId,
                 maxTokens: config.PLANNING_MAX_TOKENS,
                 thinkingLevel: config.LLM_THINKING_LEVEL,
                 onUsage: (rawUsage) => recordLlmUsage(model, rawUsage, { component: 'coordinator', complexity, observer }),
@@ -381,9 +501,15 @@ export class PlanningService implements IPlanningService {
           logger.warn('[PlanningService] Coordinator produced no runnable researchers (empty queries); using single-researcher fallback');
           plan = this.capResearcherQueries(this.buildFallbackCoordinatorPlan(responseText, query), complexity, this.name);
       }
-      if (plan.action !== 'synthesize') {
-          plan.action = 'delegate';
-      }
+      // Round 1 always delegates. `action` is optional in the parsed schema and the
+      // coordinator prompt neither documents nor asks for one, so any value here is
+      // the model volunteering — and the only value that changes anything is
+      // "synthesize", which asks to ship an answer written before a single source was
+      // read. With researchers present it slipped past the emptiness guard above, ended
+      // the loop at round 1, and became the final report: no queries, no scrapes, no
+      // citations, from a tool whose entire contract is grounded research. Nothing
+      // downstream wants a coordinator synthesis, so it is not honoured here.
+      plan.action = 'delegate';
       this.currentPlans.set(sessionId, plan);
 
       return plan;
@@ -422,16 +548,37 @@ export class PlanningService implements IPlanningService {
   }
 
   /**
-   * Update plan / evaluate progress after a round
+   * Update plan / evaluate progress after a round.
+   *
+   * This is TWO jobs behind one entry point, selected by `mustSynthesize`:
+   *
+   * - **Routing** (`mustSynthesize` falsy) — decide whether the run continues. Reads the
+   *   researchers' COVERAGE DIGESTS, not their findings. It still grows with the number
+   *   of researchers, but by one digest each rather than one report each — measured at
+   *   two orders of magnitude less per researcher. It cannot produce the report.
+   * - **Synthesis** (`mustSynthesize` true) — write the report. Reads every report in
+   *   full, exactly once, at the end of the run, under a corpus budget.
+   *
+   * They were one call reading the full corpus every round. That conflation is what made
+   * evaluator input grow with the square of the round count (round n re-sent rounds
+   * 1..n), put the final call at risk of exceeding the model's context window, and made
+   * the request shape uncacheable — a fresh single user message rebuilt each round, whose
+   * cache breakpoint therefore never matched. Splitting the roles removes the repetition
+   * rather than discounting it, so it needs no caching and behaves the same on every
+   * provider.
    */
   async updatePlanForRound(options: UpdatePlanOptions): Promise<ResearchPlan> {
     const { sessionId, query, complexity, round, model, reports, mustSynthesize, signal, observer, steeringMessages, modelRegistry } = options;
-    
-    logger.log(`[PlanningService] Evaluating Round ${round} findings for: "${query}"`);
+
+    // The router runs on every round except the terminal one; synthesis runs once.
+    const isRouter = !mustSynthesize;
+    const role = isRouter ? 'router' : 'synthesizer';
+
+    logger.log(`[PlanningService] ${isRouter ? 'Routing after' : 'Synthesizing at'} Round ${round} for: "${query}"`);
 
     const config = options.config ?? getConfig(options.cwd);
-    const promptTemplate = loadPrompt('system-lead-evaluator');
-    
+    const promptTemplate = loadPrompt(isRouter ? 'system-lead-router' : 'system-lead-synthesizer');
+
     const maxTeamSize = this.getTeamSize(complexity);
     const queryBudget = this.getQueryBudget(complexity);
     // Prefer the caller's live, steering-extended round budget (e.g. the
@@ -440,8 +587,32 @@ export class PlanningService implements IPlanningService {
     // the base per-complexity value when the caller doesn't supply one, so
     // callers that don't pass it (other/test callers) keep prior behavior.
     const maxRounds = options.maxRounds ?? _getMaxRounds(complexity);
-    const complexityGuidance = this.getEvaluatorComplexityGuidance(complexity);
-    const roundPhaseGuidance = this.getRoundPhaseGuidance(round, maxRounds, complexity, maxTeamSize);
+    // The round budget counts ITERATIONS, and the last one only ever synthesizes — the
+    // orchestrator leaves the loop before dispatching anyone. Phase guidance is about
+    // how much RESEARCH is left, so it must be computed against the rounds that can
+    // still research, not against the iteration count.
+    //
+    // Passing the raw budget told the router it had a round in hand that did not exist.
+    // At round 2 of 3 that is the difference between MIDDLE ("prefer delegation... with
+    // 1 round remaining") and LATE ("synthesize if the core question is answerable").
+    //
+    // To be precise about what was and was not wrong, because an earlier revision of
+    // this comment overstated it: a delegation made at round 2 DOES run — its
+    // researchers execute and their findings reach the synthesizer. What did not exist
+    // was the round AFTER it. The router was being calibrated as though it had another
+    // routing decision coming, when the one it was making was its last.
+    //
+    // Consequence worth naming: with the complexity table's 2/3/3 budgets, an unsteered
+    // run reaches the router exactly once, at the final research round, so LATE is the
+    // only phase it ever sees. That is correct — it IS the last decision — but it means
+    // the EARLY/MIDDLE branches are reachable only once steering has extended the
+    // budget. Anyone re-tuning this ladder should know the unsteered path no longer
+    // exercises it.
+    const researchRounds = Math.max(1, maxRounds - 1);
+    // Both of these are phrased against researchRounds, and must be: they land in the
+    // same prompt, and a router shown two different round budgets believes the larger.
+    const complexityGuidance = this.getEvaluatorComplexityGuidance(complexity, researchRounds);
+    const roundPhaseGuidance = this.getRoundPhaseGuidance(round, researchRounds, complexity, maxTeamSize);
 
     // Inject steering if present
     let steeringSection = '';
@@ -464,44 +635,69 @@ export class PlanningService implements IPlanningService {
       ? `\n## Previously Executed Queries\n${previousQueries.map(q => `- ${q}`).join('\n')}\n`
       : '';
 
-    const systemPrompt = injectCurrentDate(promptTemplate, 'evaluator');
-    const populatedPrompt = this.populatePrompt(systemPrompt, {
-      root_query: query,
-      round_number: round,
-      max_rounds: maxRounds,
+    // Both lead prompts are deliberately ROUND-INVARIANT: they interpolate only values
+    // that are fixed for the whole run (complexity, team size, query budget, the
+    // disabled-tool list). Everything that changes between rounds — root query, round
+    // number, agenda, executed queries, steering, round-phase guidance — is appended to
+    // the END of the user message instead (see runContext below).
+    //
+    // The reason is prompt caching. Every provider caches on an exact prefix of the
+    // serialized request, and the system prompt is the front of that prefix: a single
+    // round-varying byte in it invalidates the entire request. Anthropic-style caching
+    // makes this sharper still — pi-ai places one cache_control breakpoint at the end of
+    // the system prompt (on `anthropic-messages`, and on `openai-completions` whenever
+    // the provider's `compat.cacheControlFormat` is "anthropic"), so a system prompt that
+    // changes each round means that breakpoint is written and never read, and because
+    // invalidation is hierarchical (tools -> system -> messages) the message-level
+    // breakpoint cannot hit either.
+    //
+    // Keeping it invariant means round 2+ re-reads one cache entry that is also shared by
+    // every other run at the same complexity. Measured with llm_cache_read_tokens_total
+    // (see utils/llm-usage.ts). Note this is a real but SMALL win: what dominated the
+    // evaluator's input was the findings corpus, and that is addressed structurally by
+    // the router/synthesizer split rather than by caching.
+    const systemPrompt = injectCurrentDate(promptTemplate, role);
+    // `partial_synthesis_section` is the only run-varying value either template takes, and
+    // only the synthesizer uses it — it names which reduce pass this call is. A
+    // single-pass synthesis and every router call pass '', so their system prompts stay
+    // byte-identical across the whole run.
+    const populate = (partialSection: string): string => this.populatePrompt(systemPrompt, {
       complexity_label: complexity === 1 ? 'Level 1 (Normal)' : complexity === 2 ? 'Level 2 (Deep)' : 'Level 3 (Ultra)',
-      initial_agenda_section: initialAgendaSection,
-      previous_queries_section: previousQueriesSection,
-      additional_considerations: steeringSection,
       disabled_tools_section: disabledToolsSection,
       complexity_guidance: complexityGuidance,
-      round_phase_guidance: roundPhaseGuidance,
       max_team_size: maxTeamSize,
       query_budget: queryBudget,
       youtube_query_every_n: config.YOUTUBE_QUERY_EVERY_N,
+      partial_synthesis_section: partialSection,
     });
 
-    // Normalize citations across all reports to ONE global numbering BEFORE the
-    // evaluator/synthesis LLM sees them, and hand it the matching Global Source
-    // List. The evaluator prompt promises exactly this ("reports have already
-    // been normalized to these global numbers"); doing it here is what makes the
-    // synthesized body's [N] line up with the final CITED LINKS list that
-    // ensureCitedLinks() regenerates from the same normalization.
-    const { normalizedReports, globalCitations } = normalizeCitations(reports);
-    const globalSourceList = globalCitations.length > 0
-      ? 'GLOBAL SOURCE LIST (use these exact [N] numbers for every inline citation):\n' +
-        globalCitations
-          .map((c) => `[${c.id}] ${c.url}${c.source ? ` [Source: ${c.source}]` : ''}${c.description ? ` — ${c.description}` : ''}`)
-          .join('\n') +
-        '\n\n---\n\n'
-      : '';
-    const findings = globalSourceList + Array.from(normalizedReports.entries())
-        .map(([id, report]) => `### Researcher ${id}\n${report}`)
-        .join('\n\n');
-
-    const userMessage = mustSynthesize 
-        ? `Research budget exhausted. Synthesize final report now based on findings:\n\n${findings}`
-        : `Evaluate the following findings and decide next steps (delegate more researchers or synthesize final report):\n\n${findings}`;
+    // Run-varying context, appended AFTER the bulk of the message (digests for the
+    // router, findings for the synthesizer). `reports` is cumulative and iterated in
+    // insertion order, and normalizeCitations assigns global ids by first appearance in
+    // that same order, so a report written in round 1 is byte-identical in later rounds'
+    // messages. Anything placed before it would destroy that: the global source list used
+    // to sit at the front and grew by a line per new URL, which moved every byte after it.
+    const runContext = [
+      `## RUN CONTEXT`,
+      `- **ROOT QUERY**: ${query}`,
+      // Router only, and in RESEARCH rounds — the same denominator as the phase
+      // guidance below, because two different round counts in one prompt is worse than
+      // either alone. The router's only decision is delegate-vs-synthesize, and the
+      // trailing synthesis pass is not a round it can spend.
+      //
+      // Omitted for the synthesizer, which has no round decision to calibrate. Showing
+      // it there reintroduced the impossible round number this denominator was meant to
+      // remove: the forced final synthesis runs AT the cap, so it read "Current round:
+      // 2 / 1" on every complexity-1 run — and then promised a final synthesis pass to
+      // the call that was itself the final synthesis pass.
+      isRouter ? `- **Current round**: ${round} / ${researchRounds} (research rounds; a final synthesis pass follows)` : '',
+      initialAgendaSection.trim(),
+      previousQueriesSection.trim(),
+      // Round-phase guidance calibrates a ROUTING decision against the round budget. The
+      // terminal synthesis has no decision left to make, so it is omitted there.
+      isRouter ? roundPhaseGuidance.trim() : '',
+      steeringSection.trim(),
+    ].filter(Boolean).join('\n\n');
 
     try {
       const authResult = await safeGetApiKeyAndHeaders(modelRegistry, model);
@@ -509,52 +705,58 @@ export class PlanningService implements IPlanningService {
         throw new Error(`Failed to get API key for evaluation: ${authResult.error}`);
       }
 
-      const llmTimeout = config.LLM_TIMEOUT_MS;
+      const callOptions = {
+        model,
+        apiKey: authResult.apiKey || '',
+        headers: authResult.headers,
+        signal,
+        sessionId,
+        config,
+        complexity,
+        observer,
+      };
 
-      // Retry the transport call + validation on transient failures (see generatePlan for the
-      // rationale — a "terminated" abort only throws at validateAndExtractText, so validation
-      // must be inside the retried region; repair/fallback stays outside).
-      const { response, responseText } = await retryWithBackoff(
-        async () => {
-          const response = await withTimeout(
-            completeSimple(model, {
-              systemPrompt: populatedPrompt,
-              messages: [
-                { role: 'user', content: [{ type: 'text', text: userMessage }], timestamp: Date.now() },
-              ],
-              // The evaluator's response carries the final report whenever it synthesizes —
-              // which it may choose to do on ANY round (voluntary early finish), not just the
-              // forced final round. So every evaluator call gets the full synthesis budget; a
-              // small decision response simply uses a fraction of it. Clamped to the model.
-            }, buildSafeOptions(model, {
-              apiKey: authResult.apiKey || '',
-              headers: authResult.headers,
-              signal
-            }, config.SYNTHESIS_MAX_TOKENS, config.LLM_THINKING_LEVEL)),
-            llmTimeout, 'evaluator-updatePlanForRound',
-          );
-          const responseText = validateAndExtractText(response, 'Evaluator');
-          return { response, responseText };
-        },
-        {
-          maxRetries: LLM_MAX_RETRIES,
-          initialDelay: LLM_RETRY_INITIAL_DELAY_MS,
-          maxDelay: LLM_RETRY_MAX_DELAY_MS,
-          label: 'evaluator-updatePlanForRound',
-          signal,
-          isTransientError: (err) => isRetriableLlmError(err, signal),
-        },
-      );
-
-      // Track usage once, on the successful attempt (failed attempts throw before here).
-      recordLlmUsage(model, (response as any).usage, { component: 'evaluator', complexity, observer });
+      const responseText = isRouter
+        ? await (() => {
+            const routerMessage = buildRouterMessage(...this.buildRouterEvidence(options, round), runContext);
+            // The router carries no reduce mechanism the way synthesizeCorpus does — a
+            // routing decision made from PARTITIONED evidence isn't naturally mergeable
+            // the way synthesis prose is, and this call's output is a structured JSON
+            // delegate plan, not free text. Its input is bounded by team size in the
+            // common case (digests for earlier rounds are already capped — see
+            // MAX_DIGEST_CHARS), but nothing caps an individual researcher's fresh report
+            // body, so a round with a few unusually long reports can still overflow the
+            // window with no reduce path to fall back on. Warn rather than fail silently;
+            // the provider's own rejection is still the actual backstop, same as the
+            // synthesizer's over-budget-after-every-pass case above.
+            const window = model.contextWindow ?? DEFAULT_MODEL_CONTEXT_WINDOW;
+            const estimatedTokens = routerMessage.length / CHARS_PER_TOKEN + ROUTER_MAX_TOKENS + SYNTHESIS_OVERHEAD_TOKENS;
+            if (estimatedTokens > window) {
+              logger.warn(
+                `[PlanningService] Router request for ${model.id} is an estimated ` +
+                `${Math.round(estimatedTokens)} tokens against a ${window}-token context window ` +
+                `(evidence ${routerMessage.length} chars, output ceiling ${ROUTER_MAX_TOKENS} tokens). ` +
+                `Unlike the synthesizer, the router has no reduce path for an over-budget round — ` +
+                `sending it anyway, the provider may reject this request.`,
+              );
+            }
+            return this.callLead({
+              ...callOptions,
+              systemPrompt: populate(''),
+              userMessage: routerMessage,
+              maxTokens: ROUTER_MAX_TOKENS,
+              component: 'router',
+              label: 'router-updatePlanForRound',
+            });
+          })()
+        : await this.synthesizeCorpus({ ...callOptions, reports, runContext, populate });
 
       // Extract and validate JSON
       let plan: ResearchPlan | null = null;
       try {
           plan = this.parseJsonPlan(responseText);
       } catch {
-        logger.warn('[PlanningService] Evaluation JSON malformed, attempting agentic repair');
+        logger.warn(`[PlanningService] ${role} JSON malformed, attempting agentic repair`);
         const repaired = await repairJsonWithLlm<ResearchPlan>(
             responseText,
             completeSimple,
@@ -562,12 +764,13 @@ export class PlanningService implements IPlanningService {
             {
                 model,
                 schema: EvaluationResponseSchemaAsTSchema,
-                context: `Research evaluation for: ${query} (Round ${round})`,
+                context: `Research ${role} for: ${query} (Round ${round})`,
                 serviceName: 'PlanningService',
                 signal,
-                maxTokens: config.SYNTHESIS_MAX_TOKENS,
+                sessionId,
+                maxTokens: isRouter ? ROUTER_MAX_TOKENS : config.SYNTHESIS_MAX_TOKENS,
                 thinkingLevel: config.LLM_THINKING_LEVEL,
-                onUsage: (rawUsage) => recordLlmUsage(model, rawUsage, { component: 'evaluator', complexity, observer }),
+                onUsage: (rawUsage) => recordLlmUsage(model, rawUsage, { component: role, complexity, observer }),
             }
         );
         if (repaired) {
@@ -588,16 +791,20 @@ export class PlanningService implements IPlanningService {
         // if there is a prior agenda to continue, delegate another round rather than giving up.
         // Round budget (maxRounds) still bounds this, so it cannot loop indefinitely.
         if (mustSynthesize) {
-          logger.warn('[PlanningService] Failed to generate valid evaluation on the final round; synthesizing from raw text');
+          logger.warn('[PlanningService] Failed to generate valid synthesis JSON on the final round; synthesizing from raw text');
           const safeContent = salvageReportText(responseText);
           plan = { action: 'synthesize', content: safeContent, researchers: [] };
         } else if (previousPlan?.researchers && previousPlan.researchers.length > 0) {
-          logger.warn('[PlanningService] Evaluation unparseable mid-research; continuing the prior agenda rather than synthesizing early');
+          logger.warn('[PlanningService] Routing decision unparseable mid-research; continuing the prior agenda rather than finishing early');
           plan = { action: 'delegate', content: '', researchers: previousPlan.researchers };
         } else {
-          logger.warn('[PlanningService] Evaluation unparseable and no prior agenda to continue; falling back to synthesize');
-          const safeContent = salvageReportText(responseText);
-          plan = { action: 'synthesize', content: safeContent, researchers: [] };
+          // A ROUTER's raw text is never a report — it has not read the findings. Salvaging
+          // it as `content` (which is what this branch used to do, back when one call did
+          // both jobs) would ship the model's routing prose to the user as the run's
+          // output. Hand back an empty synthesis decision instead, so the orchestrator
+          // runs the real terminal synthesis over the collected reports.
+          logger.warn('[PlanningService] Routing decision unparseable and no prior agenda to continue; deferring to final synthesis');
+          plan = { action: 'synthesize', content: '', researchers: [] };
         }
       }
 
@@ -606,6 +813,29 @@ export class PlanningService implements IPlanningService {
       // Respect mustSynthesize flag
       if (mustSynthesize) {
           finalPlan.action = 'synthesize';
+      } else if (finalPlan.action === 'synthesize' && finalPlan.content) {
+        // The router is told not to write prose and is given no findings to write it from,
+        // but a model that ignores that would produce an ungrounded report — and the
+        // orchestrator would ship it verbatim. Drop it; the terminal synthesis, which does
+        // read every report, writes the output.
+        logger.warn('[PlanningService] Router returned report content despite having no findings; discarding it in favour of the final synthesis');
+        finalPlan.content = '';
+      }
+
+      // `action` is OPTIONAL in the schema, and parseJsonPlan accepts a plan without one
+      // as long as it carries researchers — its own comment says such a plan "defaults to
+      // delegation downstream", which was true of generatePlan and never of this method.
+      // A router emitting `{"researchers":[...]}` therefore fell through every branch
+      // below and was returned verbatim: no team-size cap, no per-researcher query
+      // budget, no round hard cap, and no duplicate-id renumbering — and duplicate ids
+      // collide on the `${round}.${id}` report key, silently discarding one researcher's
+      // entire report. The orchestrator then matched none of its `action === 'delegate'`
+      // branches, so it announced no decision and never grew the progress bar, yet ran
+      // the researchers anyway and the bar visibly regressed.
+      //
+      // 'wait' is preserved: the orchestrator acts on it, and it is not a delegation.
+      if (finalPlan.action !== 'synthesize' && finalPlan.action !== 'wait') {
+          finalPlan.action = 'delegate';
       }
 
       // Final safety cap if delegating
@@ -682,6 +912,266 @@ export class PlanningService implements IPlanningService {
     }
   }
 
+  /**
+   * Split what the router sees into evidence it must judge and history it already judged.
+   *
+   * The fidelity/cost trade this protocol turns on. Sending every report every round gives
+   * a correct decision but grows with the square of the round count; sending only digests
+   * is cheap but makes the decision hostage to what each researcher claims about its own
+   * work. Sending each report in full exactly ONCE — on the round it arrives — costs the
+   * corpus linearly and still puts real prose in front of every decision.
+   */
+  private buildRouterEvidence(
+    options: UpdatePlanOptions,
+    round: number,
+  ): [Map<string, { body: string; digest: string }>, Map<string, string>] {
+    const digests = this.resolveDigests(options);
+    const { freshIds, priorIds } = splitReportsByRound(options.reports, round);
+
+    const fresh = new Map<string, { body: string; digest: string }>();
+    for (const id of freshIds) {
+      fresh.set(id, {
+        body: stripCitedLinks(options.reports.get(id) ?? ''),
+        digest: digests.get(id) ?? '(none provided)',
+      });
+    }
+
+    const prior = new Map<string, string>();
+    for (const id of priorIds) {
+      const digest = digests.get(id);
+      if (digest) prior.set(id, digest);
+    }
+    // A digest whose report is gone still belongs in the history block — dropping it hides
+    // that researcher from the router entirely.
+    for (const [id, digest] of digests.entries()) {
+      if (!fresh.has(id) && !prior.has(id)) prior.set(id, digest);
+    }
+
+    return [fresh, prior];
+  }
+
+  /**
+   * Coverage digests for the router, one per researcher that has reported.
+   *
+   * Callers that hold the synthesis service pass them in. Callers that don't (tests, the
+   * SDK's direct entry points) get digests derived from the report bodies, so the router
+   * always sees an entry for every researcher rather than being handed nothing and
+   * concluding the round produced no work.
+   */
+  private resolveDigests(options: UpdatePlanOptions): Map<string, string> {
+    // Fill per REPORT, not per supplied digest. Taking `options.digests` wholesale would
+    // leave the router blind to any researcher missing from it — and a researcher the
+    // router cannot see reads as one that produced nothing, which argues for re-delegating
+    // work already done. Iterating the reports guarantees exactly one entry per researcher
+    // whatever the caller passed.
+    const supplied = options.digests;
+    const resolved = new Map<string, string>();
+    for (const [id, report] of options.reports.entries()) {
+      resolved.set(id, supplied?.get(id) ?? deriveCoverageDigest(report));
+    }
+    // A digest for an id with no report (a caller tracking them separately) is still worth
+    // showing — dropping it would hide a researcher entirely.
+    if (supplied) {
+      for (const [id, digest] of supplied.entries()) {
+        if (!resolved.has(id)) resolved.set(id, digest);
+      }
+    }
+    return resolved;
+  }
+
+  /**
+   * One lead LLM call: transport retry, timeout, text validation, usage accounting.
+   *
+   * Shared by the router and by every pass of the synthesizer so all of them get the same
+   * transient-failure handling. Retries the transport call AND validation together (see
+   * generatePlan — a "terminated" abort only throws at validateAndExtractText, so
+   * validation must sit inside the retried region); repair and fallback stay outside, in
+   * the caller.
+   */
+  private async callLead(args: {
+    model: Model<any>;
+    apiKey: string;
+    headers?: Record<string, string | null>;
+    signal?: AbortSignal;
+    sessionId: string;
+    config: Config;
+    complexity: 1 | 2 | 3;
+    observer?: UpdatePlanOptions['observer'];
+    systemPrompt: string;
+    userMessage: string;
+    maxTokens: number;
+    component: string;
+    label: string;
+  }): Promise<string> {
+    const { model, signal, config, complexity, observer, label } = args;
+
+    const { response, responseText } = await retryWithBackoff(
+      async () => {
+        const response = await withTimeout(
+          completeSimple(model, {
+            systemPrompt: args.systemPrompt,
+            messages: [
+              { role: 'user', content: [{ type: 'text', text: args.userMessage }], timestamp: Date.now() },
+            ],
+          }, buildSafeOptions(model, {
+            apiKey: args.apiKey,
+            headers: args.headers,
+            signal,
+            sessionId: args.sessionId,
+          }, args.maxTokens, config.LLM_THINKING_LEVEL)),
+          config.LLM_TIMEOUT_MS, label,
+        );
+        const responseText = validateAndExtractText(response, label);
+        return { response, responseText };
+      },
+      {
+        maxRetries: LLM_MAX_RETRIES,
+        initialDelay: LLM_RETRY_INITIAL_DELAY_MS,
+        maxDelay: LLM_RETRY_MAX_DELAY_MS,
+        label,
+        signal,
+        isTransientError: (err) => isRetriableLlmError(err, signal),
+      },
+    );
+
+    // Track usage once, on the successful attempt (failed attempts throw before here).
+    recordLlmUsage(model, (response as any).usage, { component: args.component, complexity, observer });
+    return responseText;
+  }
+
+  /**
+   * Produce the final report from the full corpus, in one pass when it fits and a bounded
+   * reduce when it does not.
+   *
+   * The reduce exists because this is the only call whose input is unbounded, and its
+   * failure mode is the worst in the system: the provider rejects an over-window request
+   * after the whole run has been paid for, and the user receives a mechanical
+   * concatenation of raw reports. Partitioning trades one guaranteed-to-fit pass per
+   * partition plus a merge for that cliff.
+   */
+  private async synthesizeCorpus(args: {
+    model: Model<any>;
+    apiKey: string;
+    headers?: Record<string, string | null>;
+    signal?: AbortSignal;
+    sessionId: string;
+    config: Config;
+    complexity: 1 | 2 | 3;
+    observer?: UpdatePlanOptions['observer'];
+    reports: Map<string, string>;
+    runContext: string;
+    populate: (partialSection: string) => string;
+  }): Promise<string> {
+    const { config, reports, runContext, populate } = args;
+
+    // Normalize citations across all reports to ONE global numbering BEFORE the synthesis
+    // LLM sees them, and hand it the matching Global Source List. The synthesizer prompt
+    // promises exactly this ("reports have already been normalized to these global
+    // numbers"); doing it here is what makes the synthesized body's [N] line up with the
+    // final CITED LINKS list that ensureCitedLinks() regenerates from the same
+    // normalization. Done once, before partitioning, so every partial pass sees the same
+    // global numbering as the merge.
+    const { normalizedReports, globalCitations } = normalizeCitations(reports);
+    const globalSourceList = globalCitations.length > 0
+      ? 'GLOBAL SOURCE LIST (use these exact [N] numbers for every inline citation):\n' +
+        globalCitations
+          .map((c) => `[${c.id}] ${c.url}${c.source ? ` [Source: ${c.source}]` : ''}${c.description ? ` — ${c.description}` : ''}`)
+          .join('\n')
+      : '';
+
+    const budgetChars = synthesisCorpusBudgetChars(
+      args.model,
+      config.SYNTHESIS_MAX_TOKENS,
+      globalSourceList.length + runContext.length,
+    );
+
+    let entries: Array<[string, string]> = Array.from(normalizedReports.entries())
+      .map(([id, report]) => [`Researcher ${id}`, truncateToBudget(report, budgetChars, id)] as [string, string]);
+
+    let pass = 0;
+    let reduced = false;
+    while (pass < MAX_SYNTHESIS_REDUCE_PASSES) {
+      const partitions = partitionCorpus(entries, entrySize, budgetChars);
+      if (partitions.length <= 1) break;
+      reduced = true;
+      logger.warn(
+        `[PlanningService] Synthesis corpus (${entries.reduce((n, e) => n + entrySize(e), 0)} chars) exceeds the ` +
+        `${budgetChars}-char budget for ${args.model.id}; reducing in ${partitions.length} partial passes (pass ${pass + 1})`,
+      );
+      // Budget each partial's OUTPUT so that all of them together fit the next pass's
+      // input. Left at the full synthesis ceiling, N partials can total N x 32k tokens —
+      // larger than the corpus they replaced — so the reduce would need pass after pass to
+      // converge and could still run out of passes. Dividing the budget makes one pass
+      // sufficient in practice. Floored so a wide fan-out cannot squeeze a partial down to
+      // uselessly few tokens; if the floor binds, the extra passes below absorb it.
+      const partialMaxTokens = Math.min(
+        config.SYNTHESIS_MAX_TOKENS,
+        Math.max(
+          MIN_PARTIAL_SYNTHESIS_TOKENS,
+          Math.floor(budgetChars / CHARS_PER_TOKEN / partitions.length),
+        ),
+      );
+      const next: Array<[string, string]> = [];
+      for (const [index, partition] of partitions.entries()) {
+        const text = await this.callLead({
+          ...args,
+          systemPrompt: populate(partialSynthesisSection(index + 1, partitions.length)),
+          userMessage: buildSynthesisMessage(partition, globalSourceList, runContext, true),
+          maxTokens: partialMaxTokens,
+          component: 'synthesizer',
+          label: `synthesizer-reduce-${pass + 1}.${index + 1}`,
+        });
+        next.push([`Partial synthesis ${index + 1}`, unwrapPartialSynthesis(text, this)]);
+      }
+      entries = next;
+      pass++;
+    }
+
+    // Exiting on the pass cap with the corpus still over budget means the request below is
+    // knowingly oversized. Say so: a silent truncation-or-overflow here reads downstream as
+    // "the model refused", and the run has already been paid for by this point.
+    const finalSize = entries.reduce((n, e) => n + entrySize(e), 0);
+    if (finalSize > budgetChars) {
+      logger.warn(
+        `[PlanningService] Synthesis corpus is still ${finalSize} chars after ` +
+        `${MAX_SYNTHESIS_REDUCE_PASSES} reduce pass(es), over the ${budgetChars}-char budget for ` +
+        `${args.model.id}. Sending it anyway — the provider may reject this request.`,
+      );
+    }
+
+    // budgetChars alone can UNDER-report overflow risk once it hits MIN_SYNTHESIS_CORPUS_CHARS:
+    // below that point it is a fixed floor, not a value derived from the window, so a reduced
+    // corpus that fits comfortably under the floor can still combine with a large global source
+    // list and/or run context (neither bounded, both already subtracted from budgetChars but not
+    // from THIS check) to overflow the real window — the same failure class the budget exists to
+    // prevent, just triggered by those two inputs growing instead of the corpus. Check the actual
+    // total request against the actual window directly, independent of any floor.
+    const window = args.model.contextWindow ?? DEFAULT_MODEL_CONTEXT_WINDOW;
+    const estimatedTotalTokens =
+      (finalSize + globalSourceList.length + runContext.length) / CHARS_PER_TOKEN +
+      config.SYNTHESIS_MAX_TOKENS + SYNTHESIS_OVERHEAD_TOKENS;
+    if (estimatedTotalTokens > window) {
+      logger.warn(
+        `[PlanningService] Synthesis request for ${args.model.id} is an estimated ` +
+        `${Math.round(estimatedTotalTokens)} tokens against a ${window}-token context window ` +
+        `(corpus ${finalSize} chars, source list ${globalSourceList.length} chars, run context ` +
+        `${runContext.length} chars, output ceiling ${config.SYNTHESIS_MAX_TOKENS} tokens) — the ` +
+        `source list and/or run context are large enough on their own to overflow the window even ` +
+        `though the reduced corpus fits its budget. Sending it anyway — the provider may reject ` +
+        `this request.`,
+      );
+    }
+
+    return this.callLead({
+      ...args,
+      systemPrompt: populate(reduced ? MERGE_SYNTHESIS_SECTION : ''),
+      userMessage: buildSynthesisMessage(entries, globalSourceList, runContext, false),
+      maxTokens: config.SYNTHESIS_MAX_TOKENS,
+      component: 'synthesizer',
+      label: 'synthesizer-final',
+    });
+  }
+
   /**
    * Generate queries for a researcher
    */
@@ -689,3 +1179,188 @@ export class PlanningService implements IPlanningService {
     return options.researcher.queries || [];
   }
 }
+
+/**
+ * Take the prose out of a partial pass's response, whatever shape it arrived in.
+ *
+ * A partial pass is told to return plain text, and the override that says so is now the
+ * last thing in its prompt. A model can still return the synthesis envelope out of habit —
+ * and if it does, the merge pass would receive a raw JSON blob where it expects prose,
+ * then dutifully reproduce the braces in the final report. Unwrapping here costs one
+ * parse attempt and makes the reduce independent of that going right.
+ */
+function unwrapPartialSynthesis(text: string, service: { parseJsonPlan(t: string): ResearchPlan }): string {
+  const trimmed = text.trim();
+  if (!trimmed.includes('"content"')) return trimmed;
+  try {
+    const parsed = service.parseJsonPlan(trimmed);
+    const content = typeof parsed.content === 'string' ? parsed.content.trim() : '';
+    if (content) {
+      logger.debug('[PlanningService] Partial synthesis returned a JSON envelope; unwrapped its content');
+      return content;
+    }
+  } catch {
+    // Not an envelope — it is prose that happens to mention "content". Use it as written.
+  }
+  return trimmed;
+}
+
+/** Chars a corpus entry contributes, including its `### <label>` heading line. */
+function entrySize(entry: [string, string]): number {
+  return entry[1].length + entry[0].length + 8;
+}
+
+/**
+ * Cut a single report that is larger than the entire corpus budget.
+ *
+ * Reached only when one researcher produced more text than the model can hold at once, at
+ * which point there is no partitioning left to do — the choice is a truncated report or a
+ * rejected request. The marker is left in the text so the model knows the tail is missing
+ * rather than treating the cut as the end of the findings.
+ */
+function truncateToBudget(report: string, budgetChars: number, id: string): string {
+  if (report.length <= budgetChars) return report;
+  logger.warn(
+    `[PlanningService] Report ${id} (${report.length} chars) exceeds the whole synthesis corpus budget ` +
+    `(${budgetChars}); truncating it — the tail of this report will not reach the final report`,
+  );
+  return `${report.slice(0, budgetChars)}\n\n[report truncated: exceeded the synthesis context budget]`;
+}
+
+/**
+ * Which reports the router has not read in full yet.
+ *
+ * A report is FRESH on the one round it arrives, and thereafter is represented by its
+ * digest — the router already read it, and re-sending it is the repetition this protocol
+ * exists to remove. Derived from the `${round}.${id}` key the synthesis service stores
+ * under, so it needs no extra state and survives a `wait` retry re-running the same round.
+ *
+ * An id with no parseable round prefix is treated as FRESH. That errs toward showing the
+ * router more evidence: the failure mode of guessing wrong in the other direction is a
+ * decision made without ever having seen a finding.
+ */
+export function splitReportsByRound(
+  reports: ReadonlyMap<string, string>,
+  currentRound: number,
+): { freshIds: string[]; priorIds: string[] } {
+  const freshIds: string[] = [];
+  const priorIds: string[] = [];
+  for (const id of reports.keys()) {
+    const round = Number.parseInt(id.split('.')[0] ?? '', 10);
+    // Reports produced during round `currentRound - 1` are the ones this call is judging.
+    // `>=` rather than `===` so a round that produced nothing cannot strand a later
+    // report in the "already reviewed" bucket it was never shown in.
+    if (!Number.isFinite(round) || round >= currentRound - 1) freshIds.push(id);
+    else priorIds.push(id);
+  }
+  return { freshIds, priorIds };
+}
+
+/**
+ * Drop the trailing CITED LINKS section from a report body.
+ *
+ * Routing needs the findings, not the bibliography — and the bibliography is a large share
+ * of a report, since the researcher prompt asks for 3–6 dense sentences per source. The
+ * digest already carries the source count, which is the only part of it a routing decision
+ * uses. Anchored on a real line-leading header, never an incidental mention in prose.
+ */
+function stripCitedLinks(report: string): string {
+  const { lineStart } = lastCitedLinksHeader(report);
+  return (lineStart >= 0 ? report.slice(0, lineStart) : report).trim();
+}
+
+/**
+ * The router's user message.
+ *
+ * Earlier rounds come FIRST and are append-only — round r's block is a byte-identical
+ * prefix of round r+1's — so the stable part of the request sits where a prompt cache can
+ * hold it, and the volatile new reports sit after it.
+ *
+ * Each fresh report is shown with the digest its researcher wrote for it. That pairing is
+ * the point: a self-reported "Gaps: none" sitting next to thin prose is visible as a
+ * mismatch, where a digest on its own has to be taken on trust.
+ */
+export function buildRouterMessage(
+  fresh: ReadonlyMap<string, { body: string; digest: string }>,
+  priorDigests: ReadonlyMap<string, string>,
+  runContext: string,
+): string {
+  const priorBlock = priorDigests.size > 0
+    ? `## REVIEWED IN EARLIER ROUNDS\nYou read these reports in full when they arrived and already judged them. Only their coverage digests are repeated here.\n\n${formatDigestsForRouter(priorDigests)}`
+    : '';
+
+  const freshBlock = fresh.size > 0
+    ? `## NEW SINCE YOUR LAST DECISION — FULL REPORTS\nJudge these on the evidence in the reports themselves. Each carries the digest its researcher wrote; treat that as a claim to check against the report below it, not as a fact.\n\n${
+        Array.from(fresh.entries())
+          .map(([id, r]) => `### Researcher ${id}\nResearcher's coverage claim:\n${r.digest}\n\nReport:\n${r.body || '(this researcher produced no usable report)'}`)
+          .join('\n\n')
+      }`
+    : '(No new reports since your last decision.)';
+
+  return [
+    'Findings from the research team follow.',
+    priorBlock,
+    freshBlock,
+    runContext,
+    'Decide whether the research is complete or another round is needed. Return JSON only.',
+  ].filter(Boolean).join('\n\n---\n\n');
+}
+
+/** The synthesizer's user message: corpus, global source list, run context, directive. */
+function buildSynthesisMessage(
+  entries: Array<[string, string]>,
+  globalSourceList: string,
+  runContext: string,
+  isPartialPass: boolean,
+): string {
+  const isMerge = entries.some(([label]) => label.startsWith('Partial synthesis'));
+  const leadIn = isMerge
+    ? 'Partial syntheses of the research findings follow.'
+    : 'Findings from the research team follow.';
+  const body = entries.map(([label, text]) => `### ${label}\n${text}`).join('\n\n');
+  const directive = isPartialPass
+    ? 'Write the partial synthesis for the findings above, as plain text.'
+    : 'Write the final report now, based on the findings above.';
+  return [leadIn, body, globalSourceList, runContext, directive]
+    .filter(Boolean)
+    .join('\n\n---\n\n');
+}
+
+/**
+ * Overrides the synthesizer's output contract for one partition of a reduce pass.
+ *
+ * Interpolated at the very END of the template, after the Output Requirements block, so
+ * this is the last instruction the model reads. Placed earlier it loses: the JSON-only
+ * format rule further down would be the final word, the model would return an envelope
+ * instead of prose, and the merge pass would receive raw JSON blobs where it expects
+ * partial syntheses.
+ */
+function partialSynthesisSection(index: number, total: number): string {
+  return [
+    '---',
+    '',
+    '## PARTIAL PASS — read this LAST; it OVERRIDES the Output Requirements and CITED LINKS rules above',
+    '',
+    `The run's findings did not fit in one request. You are being given partition ${index} of ${total}.`,
+    '',
+    '- Write an exhaustive, topic-organized synthesis of ONLY the findings you were given. Every rule about detail, grounding and anonymity still applies at full strength — a later pass merges your output, so anything you omit is lost for good.',
+    '- Use the global [N] numbers from the Global Source List for every inline citation, exactly as instructed above.',
+    '- Do NOT write a CITED LINKS section. The merge pass writes the single one.',
+    '- Do NOT return JSON. Return the synthesis as plain text and nothing else.',
+    '- Do NOT mention partitioning, or that other findings exist.',
+  ].join('\n');
+}
+
+/** Tells the final pass that its inputs are partial syntheses rather than raw reports. */
+const MERGE_SYNTHESIS_SECTION = [
+  '---',
+  '',
+  '## MERGE PASS',
+  '',
+  'The material above is a set of partial syntheses of this run\'s findings, each covering a different part of it. Merge them into one report.',
+  '',
+  '- Reorganize across the partials BY TOPIC. Do not present them in sequence, and do not label or reference them.',
+  '- Keep every fact, date, name and statistic from every partial. Merging is not summarizing.',
+  '- Reconcile overlap: where two partials cover the same ground, state it once, keeping the citations from both.',
+  '- All other rules above — including the CITED LINKS section and the JSON output format — apply to your output as normal.',
+].join('\n');