@lincoln504/pi-research 0.1.12 → 1.0.0

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

@@ -1,848 +1,599 @@
 /**
  * Deep Research Orchestrator
  *
- * Manages the decentralized deep research lifecycle:
- * 1. Initial Planning (One-shot) - exhaustive agenda creation
- * 2. Parallel Sibling Execution - with mid-flight report injection
- * 3. Last-Man-Standing Promotion - the final sibling handles evaluation/synthesis
- *
- * State transitions are handled by the pure deepResearchReducer.
+ * Coordinates multi-round research using specialized services.
  */
 
-import { join } from 'node:path';
-import { readFileSync } from 'node:fs';
-import { fileURLToPath } from 'node:url';
-import { dirname } from 'node:path';
-import type { ExtensionContext, AgentSession } from '@mariozechner/pi-coding-agent';
-import { convertToLlm } from '@mariozechner/pi-coding-agent';
-import type { ExtendedAgentSessionEvent } from '../types/extension-context.ts';
-import { complete, type Model } from '@mariozechner/pi-ai';
-import { deepResearchReducer, isRoundComplete } from './deep-research-reducer.ts';
-import type { SystemResearchState, ResearchSibling } from './deep-research-types.ts';
-import { TextContentBlock, isTextContentBlock, parseTokenUsage, calculateTotalTokens } from '../types/llm.ts';
-import {
-  INITIAL_RESEARCHERS_LEVEL_1,
-  INITIAL_RESEARCHERS_LEVEL_2,
-  INITIAL_RESEARCHERS_LEVEL_3,
-  MAX_ROUNDS_LEVEL_1,
-  MAX_ROUNDS_LEVEL_2,
-  MAX_ROUNDS_LEVEL_3,
-  MAX_CONCURRENT_RESEARCHERS,
-  MAX_REPORT_LENGTH,
-  DEFAULT_MODEL_CONTEXT_WINDOW,
-  MAX_EXTRA_ROUNDS,
-  MAX_EVALUATOR_REPORT_LENGTH,
-  RESEARCHER_LAUNCH_DELAY_MS,
-  STATE_PROPAGATION_DELAY_MS,
-  STREAMING_UPDATE_THRESHOLD_CHARS,
-} from '../constants.ts';
-import { extractJson, extractJsonFromCodeBlocks, extractJsonObject, normalizeStringArrayDetailed } from '../utils/json-utils.ts';
-import { createResearcherSession } from './researcher.ts';
-import { injectCurrentDate } from '../utils/inject-date.ts';
-import { buildSessionContext } from '@mariozechner/pi-coding-agent';
-import { formatSharedLinksFromState } from '../utils/shared-links.ts';
+import type { ExtensionContext, AgentToolResult } from '@earendil-works/pi-coding-agent';
+import { type Model } from '@earendil-works/pi-ai';
 import { logger } from '../logger.ts';
-import { ensureAssistantResponse } from '../utils/text-utils.ts';
-import { addSlice, activateSlice, completeSlice, removeSlice, flashSlice, updateSliceTokens, type ResearchPanelState } from '../tui/research-panel.ts';
-import { getDisplayNumber, getResearcherRoleContext } from './id-utils.ts';
-
-const __filename = fileURLToPath(import.meta.url);
-const __dirname = dirname(__filename);
-
-/**
- * Strict schema for evaluator delegation response
- */
-interface EvaluatorDelegateDecision {
-  action: 'delegate';
-  queries: string[];
-}
-
-/**
- * Strict schema for evaluator synthesis decision (implicit)
- * Synthesis is any non-delegation response, so no explicit schema needed.
- */
-
-type EvalDecision =
-  | { action: 'delegate'; queries: string[] }
-  | { action: 'synthesize'; content: string };
-
-/**
- * Parse the lead evaluator's response into a typed decision.
- *
- * Delegation format (the response IS the JSON, nothing else):
- *   {"action": "delegate", "queries": ["q1", "q2"]}
- *
- * Synthesis format: any markdown text.
- * Synthesis is the safe fallback — ambiguous or unparseable output is treated
- * as synthesis to avoid prematurely extending research.
- *
- * Extraction order (most → least reliable):
- *   1. Direct JSON.parse of the trimmed response (clean model output)
- *   2. Fenced ```json code block (model wrapped it)
- *   3. Raw brace extraction — only when '{' appears within the first 200 chars,
- *      meaning the JSON is at the start of the response. JSON buried deep in a
- *      long document is almost certainly a synthesis with an inline example and
- *      must not be extracted as delegation.
- */
-function parseEvaluatorResponse(text: string): EvalDecision {
-  const trimmed = text.trim();
-
-  const tryDelegate = (parsed: unknown): EvalDecision | null => {
-    if (
-      parsed !== null &&
-      typeof parsed === 'object' &&
-      (parsed as EvaluatorDelegateDecision).action === 'delegate' &&
-      Array.isArray((parsed as EvaluatorDelegateDecision).queries) &&
-      (parsed as EvaluatorDelegateDecision).queries.length > 0
-    ) {
-      const normalized = normalizeStringArrayDetailed((parsed as EvaluatorDelegateDecision).queries);
-      if (normalized.warnings.length > 0) {
-        logger.debug('[deep-research] Evaluator query normalization warnings:', normalized.warnings.join('; '));
-      }
-      if (normalized.strings.length > 0) {
-        return { action: 'delegate', queries: normalized.strings };
-      }
-      logger.warn('[deep-research] Evaluator delegation had no valid queries after normalization');
-    }
-    return null;
-  };
-
-  // 1. Fast path: response IS the JSON object
-  if (trimmed.startsWith('{')) {
-    try {
-      const decision = tryDelegate(JSON.parse(trimmed));
-      if (decision) return decision;
-    } catch { /* not pure JSON */ }
-  }
-
-  // 2. Fenced code block (```json ... ```)
-  const codeBlockResult = extractJsonFromCodeBlocks<EvaluatorDelegateDecision>(trimmed);
-  if (codeBlockResult.success && codeBlockResult.value) {
-    const decision = tryDelegate(codeBlockResult.value);
-    if (decision) return decision;
-  }
-
-  // 3. Raw brace extraction — only if '{' is near the start (model added prose prefix
-  //    but still intended to delegate). JSON buried deep in a long synthesis is ignored.
-  const bracePos = trimmed.indexOf('{');
-  if (bracePos !== -1 && bracePos < 200) {
-    const objectResult = extractJsonObject<EvaluatorDelegateDecision>(trimmed);
-    if (objectResult.success && objectResult.value) {
-      const decision = tryDelegate(objectResult.value);
-      if (decision) {
-        logger.debug('[deep-research] Extracted delegation from prose-wrapped response (brace at pos', bracePos, ')');
-        return decision;
-      }
-    }
-  }
-
-  logger.debug('[deep-research] No valid delegation found — treating response as synthesis');
-  return { action: 'synthesize', content: text };
-}
-
-/**
- * Truncate a researcher report body to maxChars while preserving the CITED LINKS
- * and SCRAPE CANDIDATES sections that appear at the end of the document.
- * Without this, a naive slice cuts off the very URLs the evaluator needs to see.
- */
-function truncatePreservingLinks(report: string, maxChars: number): string {
-  if (report.length <= maxChars) return report;
-  const linkSectionMatch = report.match(/\n###\s*CITED\s*LINKS[\s\S]*/i);
-  const linkSection = linkSectionMatch ? linkSectionMatch[0] : '';
-  const availableForBody = maxChars - linkSection.length - 40;
-  if (availableForBody <= 0) {
-    return report.slice(0, maxChars) + '\n... (truncated) ...';
-  }
-  return report.slice(0, availableForBody) + '\n\n... (body truncated for length) ...' + linkSection;
-}
+import { safeUnref } from '../utils/safe-unref.ts';
+import { metrics } from '../utils/metrics.ts';
+import { getSteeringMessages, consumeQueuedMessages, getActiveSteeringMessages } from './session-state.ts';
+import { MAX_EXTRA_ROUNDS_WITH_STEERING } from '../constants.ts';
+import {
+  getMaxRounds,
+} from '../core/planning-utils.ts';
+import type {
+  ResearchObserver,
+} from '../core/interfaces/observer-interfaces.ts';
+import { HeadlessObserver, type HeadlessObserverOptions } from './headless-observer.ts';
+import {
+  ServiceNames,
+  type IResearchOrchestration,
+  type ResearchPlan,
+  type IKnowledgeStoreService,
+  type IResearchSynthesisService,
+} from '../core/service-interfaces.ts';
+import { getService, tryGetServiceContainerFromCtx } from '../core/service-registry.ts';
+import { getConfig } from '../config.ts';
+import type { Config } from '../config.ts';
+import type { PlanningService } from '../core/planning-service.ts';
 
 export interface DeepResearchOrchestratorOptions {
   ctx: ExtensionContext;
   model: Model<any>;
   query: string;
   complexity: 1 | 2 | 3;
-  onTokens: (n: number) => void;
-  onUpdate: () => void;
-  searxngUrl: string;
-  panelState: ResearchPanelState;
+  sessionId: string;
+  researchId: string;
+  observer?: ResearchObserver | HeadlessObserverOptions;
+  onUpdate?: (update: AgentToolResult<any>) => void;
+  config?: Config;
+  orchestrationService?: IResearchOrchestration;
+  excludeTools?: string[];
+  initialLinks?: string[];
 }
 
+/**
+ * Deep Research Orchestrator
+ *
+ * Coordinates multi-round research using specialized services.
+ */
 export class DeepResearchOrchestrator {
-  private state: SystemResearchState;
-  private activeSessions = new Map<string, AgentSession>();
-  private resolveCompletion: (result: string) => void = () => {};
-  private rejectCompletion: (err: Error) => void = () => {};
-  private completionResolved = false; // Track if we've already resolved to prevent duplicate resolutions
-
-  /** Per-sibling current context occupation (overwritten on every message_end). */
-  private siblingTokens = new Map<string, number>();
-  /** Tracks progress units already credited per sibling/evaluator to ensure full budget is met. */
-  private progressCredits = new Map<string, number>();
-  /** Resolved context window size for the selected model. */
-  private contextWindowSize: number;
-
-  private static readonly UNITS_PER_RESEARCHER = 10;
-  private static readonly LEAD_EVAL_UNITS = 5;
+  private currentRound = 0;
+  private observer: ResearchObserver | undefined;
+  private startTime: number = Date.now();
+  private config: Config;
+  private readonly sessionStart: number = Date.now();
+  private orchestrationService: IResearchOrchestration | null = null;
 
   constructor(private options: DeepResearchOrchestratorOptions) {
-    this.state = {
-      version: 1,
-      rootQuery: options.query,
-      complexity: options.complexity,
-      currentRound: 1,
-      status: 'planning',
-      lastUpdated: Date.now(),
-      initialAgenda: [],
-      allScrapedLinks: [],
-      aspects: {},
-    };
-    this.contextWindowSize = (options.model as any)?.contextWindow ?? DEFAULT_MODEL_CONTEXT_WINDOW;
-  }
-
-  private resolveResult(result: string) {
-    // Prevent duplicate resolutions
-    if (this.completionResolved) {
-      logger.warn('[deep-research] Attempting to resolve already completed research, ignoring');
-      return;
-    }
-    this.completionResolved = true;
+    this.config = options.config || getConfig(options.ctx.cwd);
     
-    if (this.options.panelState.progress) {
-      // Snap progress to 100% to ensure clean completion
-      this.options.panelState.progress.made = this.options.panelState.progress.expected;
-      this.options.onUpdate();
+    // Resolve observer: if options were provided instead of an instance, create the instance
+    if (options.observer && typeof (options.observer as any).onProgress === 'function' && !(options.observer instanceof HeadlessObserver)) {
+       this.observer = new HeadlessObserver(options.observer as HeadlessObserverOptions);
+    } else {
+       this.observer = options.observer as ResearchObserver | undefined;
     }
-    const final = result.length > MAX_REPORT_LENGTH
-      ? result.slice(0, MAX_REPORT_LENGTH) + '\n\n... (final report truncated for length) ...'
-      : result;
-    logger.log('[deep-research] Research resolved with result of length:', final.length);
-    this.resolveCompletion(final);
-  }
-
-  async run(signal?: AbortSignal): Promise<string> {
-    return new Promise((resolve, reject) => {
-      this.resolveCompletion = resolve;
-      this.rejectCompletion = (err: Error) => {
-        if (this.completionResolved) {
-          logger.warn('[deep-research] Attempting to reject already completed research, ignoring');
-          return;
-        }
-        this.completionResolved = true;
-        reject(err);
-      };
-      if (signal?.aborted) return reject(new Error('Research aborted'));
-      signal?.addEventListener('abort', () => reject(new Error('Research aborted')));
-      this.kickoff(signal).catch(reject);
-    });
-  }
 
-  private updateState(event: Parameters<typeof deepResearchReducer>[1]) {
-    this.state = deepResearchReducer(this.state, event);
+    if (options.orchestrationService) {
+      this.orchestrationService = options.orchestrationService;
+    }
+    // Validate that ctx is available
+    if (!options.ctx) {
+      throw new Error('DeepResearchOrchestrator requires ExtensionContext (ctx) to be provided');
+    }
   }
 
-  private calculateUsageCost(usage: Partial<import('../types/llm').TokenUsage>): number {
-    if (!usage || !this.options.model?.cost) return 0;
-    const modelCost = this.options.model.cost;
-    const inputCost = (modelCost.input / 1_000_000) * (usage.input ?? 0);
-    const outputCost = (modelCost.output / 1_000_000) * (usage.output ?? 0);
-    const cacheReadCost = (modelCost.cacheRead / 1_000_000) * (usage.cacheRead ?? 0);
-    const cacheWriteCost = (modelCost.cacheWrite / 1_000_000) * (usage.cacheWrite ?? 0);
-    return inputCost + outputCost + cacheReadCost + cacheWriteCost;
+  private async getOrchestrationService(): Promise<IResearchOrchestration> {
+    if (this.orchestrationService) return this.orchestrationService;
+    const container = tryGetServiceContainerFromCtx(this.options.ctx);
+    this.orchestrationService = await getService<IResearchOrchestration>(ServiceNames.RESEARCH_ORCHESTRATION, this.options.ctx, container);
+    return this.orchestrationService;
   }
 
-  private async kickoff(signal?: AbortSignal) {
-    logger.log(`[deep-research] Kickoff: status=${this.state.status}`);
-    if (this.state.status === 'planning') await this.doPlanning(signal);
-    if (this.state.status === 'researching') await this.startRound(signal);
-    if (this.state.status === 'completed') {
-      logger.log('[deep-research] Already in completed state, resolving with synthesis');
-      this.resolveResult(this.state.finalSynthesis || '');
-    }
+  private async getPlanningService(): Promise<PlanningService> {
+    const container = tryGetServiceContainerFromCtx(this.options.ctx);
+    // Pass ctx to ensure PlanningService has access to modelRegistry
+    return await getService<PlanningService>(ServiceNames.PLANNING, this.options.ctx, container);
   }
 
-  private getInitialSiblingCount(complexity: 1 | 2 | 3): number {
-    switch(complexity) {
-      case 1: return INITIAL_RESEARCHERS_LEVEL_1;
-      case 2: return INITIAL_RESEARCHERS_LEVEL_2;
-      case 3: return INITIAL_RESEARCHERS_LEVEL_3;
-    }
+  private elapsed(): string {
+    const s = Math.round((Date.now() - this.startTime) / 1000);
+    return `+${s}s`;
   }
 
-  private getMaxRounds(complexity: 1 | 2 | 3): number {
-    switch(complexity) {
-      case 1: return MAX_ROUNDS_LEVEL_1;
-      case 2: return MAX_ROUNDS_LEVEL_2;
-      case 3: return MAX_ROUNDS_LEVEL_3;
+  /**
+   * Run the multi-round research loop
+   */
+  async run(signal?: AbortSignal): Promise<string> {
+    const { model, query, complexity, researchId, ctx } = this.options;
+    const observer = this.observer;
+    const container = tryGetServiceContainerFromCtx(ctx);
+
+    // RESEARCH_MODEL contract (config.ts): the coordinator and evaluator always
+    // use the caller's model (ctx.model); RESEARCH_MODEL overrides only the
+    // researcher sub-agents. `model` is the resolved research model — it equals
+    // ctx.model on the SDK/CLI path, but on the pi-tool path it is the
+    // RESEARCH_MODEL override, so planning must key off ctx.model explicitly.
+    // Fall back to `model` when the host exposes no ctx.model.
+    const coordinatorModel = (ctx.model as Model<any> | undefined) ?? model;
+    
+    const orchestrationService = await this.getOrchestrationService();
+    const planningService = await this.getPlanningService();
+
+    // Reset services for this specific research run ID to ensure fresh state.
+    // Pass ctx so the reset targets the SAME (ctx-scoped) container the run resolves
+    // its services from — otherwise it clears state on, and runs the knowledge-store
+    // FTS/optimize pass against, the global container instead (see the finally below,
+    // which already passes ctx).
+    await orchestrationService.cleanupResearchServices(undefined, researchId, ctx, this.config);
+    
+    logger.log(`[DeepOrchestrator] Starting multi-round research (complexity ${complexity}) for: "${query}" (Run: ${researchId})`);
+    metrics.increment('research_sessions_total', 1, { mode: 'deep', complexity: String(complexity) });
+
+    // Fire onStart observer event
+    observer?.onStart?.(query, complexity);
+
+    // Consume all queued messages at the start of the research run. The
+    // returned list is exactly the messages that were 'queued' for THIS run
+    // (transitioned queued->active here); use its length below rather than
+    // getSteeringMessages(), which also counts 'active' messages left over
+    // from prior runs and would inflate the steering round bonus.
+    const consumedAtStart = consumeQueuedMessages(this.options.sessionId);
+
+    // The base round budget for this complexity level, plus extra room
+    // for any queued steering messages that arrived before this run
+    // started (and were just consumed above). Each consumed steering
+    // message unlocks one extra round, capped by
+    // MAX_EXTRA_ROUNDS_WITH_STEERING. This keeps the round budget
+    // concept simple (one number drives the loop) while letting the
+    // user push research deeper via Alt+Enter when they have queued
+    // guidance waiting to be applied.
+    const baseMaxRounds = getMaxRounds(complexity);
+    const queuedAtStart = consumedAtStart.length;
+    const steeringBonusRounds = Math.min(queuedAtStart, MAX_EXTRA_ROUNDS_WITH_STEERING);
+    let maxRounds = baseMaxRounds + steeringBonusRounds;
+    // Track total steering-driven extra rounds already granted.
+    // New steering consumed mid-run can add more budget up to the cap.
+    let totalSteeringExtraRounds = steeringBonusRounds;
+    if (steeringBonusRounds > 0) {
+      logger.log(
+        `[DeepOrchestrator] Extending round budget from ${baseMaxRounds} to ${maxRounds} ` +
+        `(${steeringBonusRounds} extra round(s) for ${queuedAtStart} queued steering message(s), ` +
+        `cap ${MAX_EXTRA_ROUNDS_WITH_STEERING})`
+      );
     }
-  }
 
-  private async doPlanning(signal?: AbortSignal) {
-    this.options.panelState.statusMessage = 'planning...';
-    this.options.onUpdate();
+    const MAX_WAIT_RETRIES = 5;
+    let waitRetryCount = 0;
+    let loopSynthesisPlan: ResearchPlan | null = null;
 
     try {
-      // Get full parent conversation context for's coordinator (emulates fork mode)
-      const branch = this.options.ctx.sessionManager.getBranch();
-      const sessionContext = buildSessionContext(branch);
-      const parentMessages = sessionContext.messages;
-
-      logger.log(`[deep-research] Planning with ${parentMessages.length} parent messages (fork mode emulation)`);
-
-      const coordinatorPromptRaw = readFileSync(join(__dirname, '..', 'prompts', 'system-coordinator.md'), 'utf-8');
-      const plannerPrompt = coordinatorPromptRaw + `\n\nQUERY: ${this.state.rootQuery}`;
-
-      const auth = await this.options.ctx.modelRegistry.getApiKeyAndHeaders(this.options.model);
-      if (!auth.ok) throw new Error(`Failed to get API credentials: ${auth.error}`);
-      
-      // Convert AgentMessages to LLM-compatible Messages
-      const llmMessages = await convertToLlm(parentMessages);
-      
-      const response = await complete(this.options.model, {
-        messages: [
-          // Include full parent conversation history (converted) + current query
-          ...llmMessages,
-          { role: 'user', content: [{ type: 'text', text: plannerPrompt }], timestamp: Date.now() }
-        ]
-      }, { apiKey: auth.apiKey!, headers: auth.headers, signal });
-
-      const usage = response.usage;
-      if (usage) {
-        const tokens = usage.totalTokens || (usage.input || 0) + (usage.output || 0) + (usage.cacheRead || 0) + (usage.cacheWrite || 0);
-        if (tokens > 0) {
-          this.options.onTokens(tokens);
-          this.options.onUpdate();
+      while (this.currentRound < maxRounds) {
+        if (signal?.aborted) throw new Error('Research aborted');
+        this.currentRound++;
+        this.startTime = Date.now();
+
+        // Refresh steering messages and consume any new queued ones at round start
+        const beforeConsume = getSteeringMessages(this.options.sessionId).filter(m => m.status === 'active').length;
+        consumeQueuedMessages(this.options.sessionId);
+        const steeringMessages = getSteeringMessages(this.options.sessionId);
+        const steeringTexts = steeringMessages.map(m => m.text);
+
+        // Dynamically extend round budget when new steering messages are consumed mid-run.
+        // The initial budget only accounts for messages present at research start;
+        // messages entered mid-research need fresh budget so the evaluator can act on them.
+        const newlyConsumed = steeringMessages.filter(m => m.status === 'active').length - beforeConsume;
+        if (newlyConsumed > 0 && totalSteeringExtraRounds < MAX_EXTRA_ROUNDS_WITH_STEERING) {
+          const additionalRounds = Math.min(newlyConsumed, MAX_EXTRA_ROUNDS_WITH_STEERING - totalSteeringExtraRounds);
+          maxRounds += additionalRounds;
+          totalSteeringExtraRounds += additionalRounds;
+          if (additionalRounds > 0) {
+            logger.log(
+              `[DeepOrchestrator] Extended round budget from ${maxRounds - additionalRounds} to ${maxRounds} ` +
+              `(${additionalRounds} extra round(s) for ${newlyConsumed} newly consumed steering message(s), ` +
+              `total steering extra: ${totalSteeringExtraRounds}/${MAX_EXTRA_ROUNDS_WITH_STEERING})`
+            );
+          }
         }
-      }
-
-      const text = response.content
-        .filter((c): c is TextContentBlock => isTextContentBlock(c))
-        .map(c => c.text)
-        .join('');
-      let agenda: string[] = [];
-      try {
-        // Extract JSON array from coordinator response
-        const result = extractJson<string[]>(text, 'array');
-
-        if (result.success && result.value && result.value.length > 0) {
-          // Normalize queries with detailed feedback
-          const normalized = normalizeStringArrayDetailed(result.value);
-
-          if (normalized.strings.length > 0) {
-            agenda = normalized.strings;
-            logger.debug(`[deep-research] Parsed ${agenda.length} agenda items from coordinator response`);
 
-            // Log any warnings
-            if (normalized.warnings.length > 0) {
-              logger.debug('[deep-research] Coordinator query normalization warnings:',
-                normalized.warnings.join('; '));
-            }
-          }
+        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);
+
+        // Check infrastructure health (advisory: logs status, never aborts the run).
+        await orchestrationService.checkHealth(this.currentRound, researchId, ctx);
+
+        // 1. Update/Generate Plan
+        let plan: ResearchPlan;
+        if (this.currentRound === 1) {
+            observer?.onPlanningStart?.(1);
+            observer?.onPlanningProgress?.('planning');
+            plan = await planningService.generatePlan({
+                sessionId: researchId,
+                query,
+                complexity,
+                model: coordinatorModel,
+                modelRegistry: ctx.modelRegistry,
+                cwd: ctx.cwd,
+                config: this.config,
+                signal,
+                observer,
+                excludeTools: this.options.excludeTools,
+                steeringMessages: steeringTexts,
+            });
         } else {
-          logger.debug('[deep-research] Could not parse agenda JSON:', result.error ?? 'unknown error');
+            const synthesisService = await getService<IResearchSynthesisService>(ServiceNames.RESEARCH_SYNTHESIS_SERVICE, ctx, container);
+            observer?.onEvaluationStart?.(this.currentRound);
+            observer?.onEvaluationProgress?.('evaluating');
+            plan = await planningService.updatePlanForRound({
+                sessionId: researchId,
+                query: query,
+                complexity,
+                round: this.currentRound,
+                model: coordinatorModel,
+                modelRegistry: ctx.modelRegistry,
+                cwd: ctx.cwd,
+                config: this.config,
+                reports: synthesisService.getAllReports(researchId),
+                previousPlan: planningService.getCurrentPlan(researchId),
+                totalResearchersPlanned: planningService.getTotalResearchersPlanned(researchId),
+                signal,
+                observer,
+                excludeTools: this.options.excludeTools,
+                steeringMessages: steeringTexts,
+            });
         }
-      } catch (err) {
-        logger.error('[deep-research] Failed to parse planning agenda JSON:', err);
-      }
-
-      if (agenda.length === 0) {
-        agenda = [this.state.rootQuery];
-        logger.warn('[deep-research] No valid agenda items found, using root query as fallback');
-      }
-
-      const initialCount = this.getInitialSiblingCount(this.state.complexity);
-      logger.log(`[deep-research] Planning complete: ${agenda.length} agenda items. Initial count: ${initialCount}`);
-
-      this.updateState({
-        type: 'PLANNING_COMPLETE',
-        agenda,
-        initialCount
-      });
-
-      // Initialise progress budget — start with only round 1 + one lead-eval; expand dynamically
-      // when the lead evaluator spawns additional rounds in promoteToLead.
-      const round1Count = Math.min(initialCount, agenda.length);
-      const initialExpected = round1Count * DeepResearchOrchestrator.UNITS_PER_RESEARCHER
-        + DeepResearchOrchestrator.LEAD_EVAL_UNITS;
-
-      this.options.panelState.progress = { expected: initialExpected, made: 0, extended: false };
-      this.options.onUpdate();
-
-    } catch (err) {
-      const errorMsg = err instanceof Error ? err.message : String(err);
-      logger.error('[deep-research] Planning failed:', err);
-      this.rejectCompletion(new Error(`Research planning failed: ${errorMsg}`));
-    } finally {
-      this.options.panelState.statusMessage = undefined;
-      this.options.onUpdate();
-    }
-  }
-
-  private async startRound(signal?: AbortSignal) {
-    const currentRound = this.state.currentRound;
-    const roundAspects = Object.values(this.state.aspects).filter(a => a.id.startsWith(`${currentRound}.`));
-    const runningAspects = roundAspects.filter(a => a.status === 'running');
-    const pendingAspects = roundAspects.filter(a => a.status === 'pending');
-
-    if (pendingAspects.length > 0) {
-      // TUI Optimization: If we are starting a fresh round (generation 1),
-      // remove slices from previous rounds to prevent horizontal crowding.
-      const isFirstGenOfRound = roundAspects.length === pendingAspects.length;
-      if (isFirstGenOfRound && currentRound > 1) {
-        const prevRoundPrefix = `${currentRound - 1}.`;
-        const prevCoordId = `coord.${currentRound - 1}`;
-        const toRemove = Array.from(this.options.panelState.slices.keys())
-          .filter(id => id.startsWith(prevRoundPrefix) || id === prevCoordId);
-        for (const id of toRemove) {
-          removeSlice(this.options.panelState, id);
+        
+        if (plan.action === 'delegate') {
+          if (this.currentRound === 1) {
+            observer?.onPlanningSuccess?.(plan);
+          } else if (this.currentRound < maxRounds) {
+            // Only announce a delegation that will actually run. At the round cap
+            // the loop breaks to synthesis below regardless of this decision, so
+            // emitting it here would grow the progress bar's expected units for
+            // researchers that never execute — the bar then visibly regresses.
+            observer?.onEvaluationDecision?.('delegate', plan, this.currentRound);
+          }
         }
-        this.options.onUpdate();
-      }
-
-      const allowedToLaunch = Math.max(0, MAX_CONCURRENT_RESEARCHERS - runningAspects.length);
-      
-      if (allowedToLaunch > 0) {
-        const toLaunch = pendingAspects.slice(0, allowedToLaunch);
-        logger.log(`[deep-research] Round ${currentRound}: Launching ${toLaunch.length} siblings (Concurrency limit: ${MAX_CONCURRENT_RESEARCHERS}).`);
-
-        for (let i = 0; i < toLaunch.length; i++) {
-          if (i > 0) await new Promise(resolve => setTimeout(resolve, RESEARCHER_LAUNCH_DELAY_MS));
-          if (signal?.aborted) break;
-          this.executeSibling(toLaunch[i]!, signal);
+        
+        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;
+                observer?.onEvaluationDecision?.('synthesize', plan, this.currentRound);
+            }
+            break;
         }
-      }
-      return;
-    }
-
-    if (runningAspects.length > 0) {
-      return;
-    }
 
-    if (roundAspects.length > 0 && isRoundComplete(this.state, currentRound)) {
-      if (!this.state.promotedId && !this.state.finalSynthesis) {
-        const allCompletedWithReports = roundAspects.filter(a => a.status === 'completed' && a.report);
-        if (allCompletedWithReports.length === 0) {
-          const allFailed = roundAspects.filter(a => a.status === 'failed');
-          const errors = allFailed.map(a => `• Researcher ${getDisplayNumber(this.state, a.id)}: ${a.error}`).join('\n');
-          this.rejectCompletion(new Error(`Research failed. All researchers encountered errors:\n\n${errors}`));
-          return;
+        if (plan.action === 'wait') {
+            waitRetryCount++;
+            observer?.onPlanningProgress?.('planning');
+            if (waitRetryCount > MAX_WAIT_RETRIES) {
+                // Don't throw away everything gathered so far. Break to final synthesis
+                // (mustSynthesize) so the user still gets a report from collected reports
+                // instead of a hard error that discards the whole run.
+                logger.warn(`[DeepOrchestrator] Max wait retries (${MAX_WAIT_RETRIES}) exceeded at Round ${this.currentRound}; synthesizing from collected reports`);
+                break;
+            }
+            logger.debug(`[DeepOrchestrator] AI requested wait, retrying Round ${this.currentRound} in 5s (retry ${waitRetryCount}/${MAX_WAIT_RETRIES})...`);
+            
+            // Abortable sleep
+            if (signal?.aborted) {
+                throw new Error('Research cancelled');
+            }
+            await new Promise<void>((resolve, reject) => {
+                const onAbort = () => {
+                    clearTimeout(timeout);
+                    reject(new Error('Research cancelled'));
+                };
+                const timeout = setTimeout(() => {
+                    signal?.removeEventListener('abort', onAbort);
+                    resolve();
+                }, 5000);
+                safeUnref(timeout);
+                signal?.addEventListener('abort', onAbort, { once: true });
+            });
+            
+            this.currentRound--; // Retry this round
+            continue;
         }
-        this.runCoordinatorEval(signal);
-        return;
-      } else if (this.state.promotedId) {
-        return;
-      }
-    }
-
-    if (this.state.status !== 'completed') {
-      if (this.state.finalSynthesis) {
-        this.resolveResult(this.state.finalSynthesis);
-      } else {
-        this.state.status = 'completed';
-        this.resolveResult('Research ended.');
-      }
-    }
-  }
-
-  private async executeSibling(aspect: ResearchSibling, signal?: AbortSignal) {
-    this.updateState({ type: 'SIBLING_STARTED', id: aspect.id });
-
-    const displayNum = getDisplayNumber(this.state, aspect.id);
-    const roleContext = getResearcherRoleContext(this.state, aspect.id);
 
-    addSlice(this.options.panelState, aspect.id, displayNum, false);
-    activateSlice(this.options.panelState, aspect.id);
-    this.options.onUpdate();
+        // Reset wait retry counter on successful actions
+        waitRetryCount = 0;
 
-    const researcherPromptRaw = readFileSync(join(__dirname, '..', 'prompts', 'researcher.md'), 'utf-8');
-    const sharedLinksMarkdown = formatSharedLinksFromState(this.state.aspects);
-    const allFindingsMarkdown = this.buildAllFindingsContext();
-    const roleContextMarkdown = this.buildRoleContext(aspect, roleContext);
-    const researcherPrompt = injectCurrentDate(researcherPromptRaw, 'researcher')
-      + '\n\n' + roleContextMarkdown
-      + '\n\n' + allFindingsMarkdown
-      + '\n\n' + sharedLinksMarkdown;
-
-    const initialPromptEstimate = Math.ceil(researcherPrompt.length / 4);
-    this.siblingTokens.set(aspect.id, initialPromptEstimate);
-    const getTokensUsed = () => this.siblingTokens.get(aspect.id) ?? 0;
-
-    updateSliceTokens(this.options.panelState, aspect.id, initialPromptEstimate, 0);
-    this.options.onUpdate();
+        // Track how many researchers were planned this round
+        // updatePlanForRound has a comment "We'll update totalResearchersPlanned in the orchestrator"
+        if (plan.action === 'delegate' && plan.researchers && plan.researchers.length > 0) {
+            planningService.incrementTotalResearchersPlanned(researchId, plan.researchers.length);
+        }
 
-    let session: AgentSession | undefined;
-    try {
-      session = await createResearcherSession({
-        cwd: this.options.ctx.cwd,
-        ctxModel: this.options.model,
-        modelRegistry: this.options.ctx.modelRegistry,
-        settingsManager: (this.options.ctx as any).settingsManager,
-        systemPrompt: researcherPrompt,
-        searxngUrl: this.options.searxngUrl,
-        extensionCtx: this.options.ctx,
-        getGlobalState: () => this.state,
-        updateGlobalLinks: (links: string[]) => {
-          this.updateState({ type: 'LINKS_SCRAPED', links });
-        },
-        getTokensUsed,
-        contextWindowSize: this.contextWindowSize,
-      });
-
-      this.activeSessions.set(aspect.id, session);
-
-      const subscription = session.subscribe((event: ExtendedAgentSessionEvent) => {
-        if (event.type === 'message_end') {
-          const usage = parseTokenUsage(event.message?.usage);
-          const tokens = calculateTotalTokens(usage);
-          const cost = this.calculateUsageCost(usage);
-
-          if (tokens > 0) {
-            if (event.message?.role === 'assistant') {
-              this.siblingTokens.set(aspect.id, tokens);
-              this.options.onTokens(tokens);
-              updateSliceTokens(this.options.panelState, aspect.id, tokens, cost);
-              this.updateState({ type: 'SIBLING_TOKENS', id: aspect.id, tokens, cost });
-              this.options.onUpdate();
-            }
-          }
-        } else if (event.type === 'message_update') {
-          // Estimate context growth from streaming text length during model generation.
-          // Cost is NOT updated here (requires exact usage from message_end).
-          // Tokens are SET (not accumulated), so we pass cost=0 to leave cost unchanged.
-          const updateMsg = event.message;
-          if (updateMsg?.role === 'assistant') {
-            // Content may be in the message object but not typed in ExtendedAgentSessionEvent
-            const content = (updateMsg as any).content;
-            if (Array.isArray(content)) {
-              const textLen = content
-                .filter(isTextContentBlock)
-                .reduce((sum, b) => sum + b.text.length, 0);
-              if (textLen > STREAMING_UPDATE_THRESHOLD_CHARS) {
-                const base = this.siblingTokens.get(aspect.id) ?? initialPromptEstimate;
-                updateSliceTokens(this.options.panelState, aspect.id, base + Math.ceil(textLen / 4), 0);
-                this.options.onUpdate();
+        // Record all queries used this round for cross-round deduplication
+        if (plan.allQueries && plan.allQueries.length > 0) {
+            planningService.addToQueryHistory(researchId, plan.allQueries);
+        }
+        
+        // 2. Search Phase + per-researcher store queries (run in parallel)
+        let researcherLinks: Map<string, string[]> | undefined;
+        let storeLinks: Map<string, { url: string; description: string }[]> | undefined;
+
+        const searchTask = (plan.allQueries && plan.allQueries.length > 0)
+          ? (async () => {
+              observer?.onSearchStart?.(plan.allQueries!);
+              const results = await orchestrationService.runSearchBurst(plan.allQueries!, this.config, signal, (links: number) => {
+                  observer?.onSearchProgress?.(links);
+              }, ctx);
+              observer?.onSearchComplete?.(results.reduce((sum, r) => sum + (r.results?.length || 0), 0));
+              researcherLinks = await orchestrationService.distributeSearchResults(plan, results);
+
+              // Merge initialLinks into Round 1 researchers if provided
+              if (this.currentRound === 1 && this.options.initialLinks && this.options.initialLinks.length > 0) {
+                if (!researcherLinks) researcherLinks = new Map();
+                for (const researcher of plan.researchers || []) {
+                  const id = String(researcher.id);
+                  const existing = researcherLinks.get(id) || [];
+                  researcherLinks.set(id, [...new Set([...existing, ...this.options.initialLinks!])]);
+                }
               }
-            }
-          }
-        } else if (event.type === 'tool_execution_end') {
-          const isError = event.isError ?? false;
-          const color = isError ? 'red' : 'green';
-          const duration = isError ? 1000 : 500;
-          flashSlice(this.options.panelState, aspect.id, color, duration, this.options.onUpdate);
-
-          if (this.options.panelState.progress) {
-            const current = this.progressCredits.get(aspect.id) ?? 0;
-            if (current < 8) {
-              const newVal = current + 1;
-              this.progressCredits.set(aspect.id, newVal);
-              this.options.panelState.progress.made += 1;
-              this.options.onUpdate();
-            }
-          }
+            })()
+          : (async () => {
+              // Even if no queries were generated, if we have initialLinks in Round 1, distribute them
+              if (this.currentRound === 1 && this.options.initialLinks && this.options.initialLinks.length > 0) {
+                researcherLinks = new Map();
+                for (const researcher of plan.researchers || []) {
+                  researcherLinks.set(String(researcher.id), [...this.options.initialLinks!]);
+                }
+              }
+            })();
+
+        const storeTask = (this.config.KNOWLEDGE_STORE_MODE !== 'none' && plan.researchers && plan.researchers.length > 0)
+          ? (async () => {
+              try {
+                const ksService = await getService<IKnowledgeStoreService>(ServiceNames.KNOWLEDGE_STORE, ctx, container);
+                if (!ksService.isReady()) {
+                  logger.debug('[DeepOrchestrator] Knowledge store service not ready, skipping per-researcher store queries');
+                  return;
+                }
+                const store = await ksService.getStore();
+                if (store && typeof store.findRelevantUrls === 'function') {
+                  const storeMap = new Map<string, { url: string; description: string }[]>();
+                  await Promise.all((plan.researchers ?? []).map(async (researcher) => {
+                    const entries = await store.findRelevantUrls(researcher.goal, { limit: 4 });
+                    if (entries.length > 0) {
+                      storeMap.set(String(researcher.id), entries);
+                      logger.debug(`[DeepOrchestrator] Researcher ${researcher.id}: ${entries.length} store URL(s) from goal query`);
+                    }
+                  }));
+                  if (storeMap.size > 0) storeLinks = storeMap;
+                }
+              } catch (err) {
+                logger.warn('[DeepOrchestrator] Per-researcher store queries failed (non-fatal):', err);
+              }
+            })()
+          : Promise.resolve();
+
+        await Promise.all([searchTask, storeTask]);
+
+        // 3. Researcher Phase
+        if (plan.researchers && plan.researchers.length > 0) {
+            // Pass this.config (the resolved Config) rather than this.options (where
+            // options.config may be undefined). runResearcher accesses researchConfig.RESEARCHER_MAX_RETRIES
+            // and similar fields — passing undefined crashes immediately.
+            // Default excludeTools to ['grep'] if not explicitly set — mirrors QuickResearchOrchestrator
+            // so that high-capability models don't waste time on developer-only tools.
+            await orchestrationService.runResearchers({
+                plan,
+                options: {
+                    ...this.options,
+                    config: this.config,
+                    excludeTools: this.options.excludeTools || ['grep'],
+                    observer: this.observer,
+                },
+                currentRound: this.currentRound,
+                signal
+            }, researcherLinks, storeLinks);
         }
-      });
 
-      const queryText = typeof aspect.query === 'string' ? aspect.query : String(aspect.query);
-      await session.prompt(queryText);
-
-      if (signal?.aborted) {
-        if (typeof subscription === 'function') subscription();
-        this.updateState({ type: 'SIBLING_FAILED', id: aspect.id, error: 'Aborted' });
-        return;
+        // Esc/abort responsiveness: runResearchers returns NORMALLY when the signal
+        // fires (researchers are individually aborted), so without this check a
+        // cancelled run would still perform the full post-round embedding pass
+        // (storeLinkDescriptions → writer.drain) before the loop-top guard throws.
+        // Throw here instead — the catch below returns the partial fallback report.
+        // Skipping the store pass is safe: nothing has been enqueued for this round
+        // yet, and the FTS rebuild is an optimization pass (see cleanup below), not
+        // required for durability of previously drained rows.
+        if (signal?.aborted) throw new Error('Research aborted');
+
+        // 4. Store synthesized descriptions for semantic search
+        // Show embedding indicator in eval box while embedding runs
+        observer?.onEvaluationProgress?.('embedding');
+        await orchestrationService.storeLinkDescriptions(researchId, this.currentRound, researchId, this.config, ctx);
+
+        // 5. Evaluation Phase
+        observer?.onEvaluationProgress?.('evaluating');
       }
 
-      const report = ensureAssistantResponse(session, aspect.id);
-      if (typeof subscription === 'function') subscription();
-
-      this.updateState({ type: 'SIBLING_COMPLETED', id: aspect.id, report });
-
-      const currentRound = this.state.currentRound;
-      const isLastStanding = isRoundComplete(this.state, currentRound);
-
-      completeSlice(this.options.panelState, aspect.id);
-
-      if (this.options.panelState.progress) {
-        const alreadyCredited = this.progressCredits.get(aspect.id) ?? 0;
-        const topUp = DeepResearchOrchestrator.UNITS_PER_RESEARCHER - alreadyCredited;
-        if (topUp > 0) {
-          this.options.panelState.progress.made += topUp;
-          this.progressCredits.set(aspect.id, DeepResearchOrchestrator.UNITS_PER_RESEARCHER);
-        }
+      // 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);
+        observer?.onEvaluationProgress?.('evaluating');
       }
-      this.options.onUpdate();
 
-      if (isLastStanding) {
-        await this.handleSiblingCompletion(aspect, signal);
+      // Final synthesis is beginning: flip steering OFF *before* the final drain
+      // below. Ordering matters — there is no next round, so a message queued after
+      // the drain would show the affirmative "will steer the next research round"
+      // 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
+      // 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.
+      consumeQueuedMessages(this.options.sessionId);
+      const finalSteeringTexts = getSteeringMessages(this.options.sessionId).map(m => m.text);
+
+      let finalReport: ResearchPlan;
+      if (loopSynthesisPlan !== null) {
+          finalReport = loopSynthesisPlan;
       } else {
-        await this.injectFindingsIntoRunningSiblings(aspect);
+          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,
+              signal,
+              observer,
+              excludeTools: this.options.excludeTools,
+              steeringMessages: finalSteeringTexts,
+          });
       }
 
-    } catch (err) {
-      if (signal?.aborted) return;
-      const errorMsg = String(err);
-      logger.error(`[deep-research] Sibling ${aspect.id} failed:`, err);
-      this.updateState({ type: 'SIBLING_FAILED', id: aspect.id, error: errorMsg });
-      flashSlice(this.options.panelState, aspect.id, 'red', 1000, this.options.onUpdate);
-      completeSlice(this.options.panelState, aspect.id);
-
-      if (this.options.panelState.progress) {
-        const alreadyCredited = this.progressCredits.get(aspect.id) ?? 0;
-        const topUp = DeepResearchOrchestrator.UNITS_PER_RESEARCHER - alreadyCredited;
-        if (topUp > 0) {
-          this.options.panelState.progress.made += topUp;
-          this.progressCredits.set(aspect.id, DeepResearchOrchestrator.UNITS_PER_RESEARCHER);
-        }
+      // 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);
       }
-      this.options.onUpdate();
 
-      const currentRound = this.state.currentRound;
-      if (isRoundComplete(this.state, currentRound)) {
-        await this.handleSiblingCompletion(aspect, signal);
+      let result = finalReport.content || '';
+      
+      // If content is empty but we have reports, build a fallback synthesis
+      if (!result.trim()) {
+          const synthesisService = await getService<IResearchSynthesisService>(ServiceNames.RESEARCH_SYNTHESIS_SERVICE, ctx, container);
+          if (synthesisService.hasReports(researchId)) {
+              logger.warn(`[DeepOrchestrator] LLM returned empty synthesis for ${researchId}, building fallback from ${synthesisService.getReportCount(researchId)} reports`);
+              result = synthesisService.buildFallbackSynthesis(researchId, this.currentRound);
+          } else {
+              result = 'Research completed but no summary was generated.';
+          }
       }
-    } finally {
-      this.activeSessions.delete(aspect.id);
-      this.startRound(signal).catch(() => {});
-    }
-  }
 
-  private async injectFindingsIntoRunningSiblings(finished: ResearchSibling) {
-    if (!finished.report) return;
-    const currentRound = this.state.currentRound;
-    const allInRound = Object.values(this.state.aspects).filter(a => a.id.startsWith(`${currentRound}.`));
-    const runningSiblings = allInRound.filter(s => s.status === 'running' && s.id !== finished.id);
-
-    for (const target of runningSiblings) {
-      const targetSession = this.activeSessions.get(target.id);
-      if (targetSession) {
-        const finishedDisplayNum = getDisplayNumber(this.state, finished.id);
-        const truncatedReport = truncatePreservingLinks(finished.report, MAX_EVALUATOR_REPORT_LENGTH);
-        const injectionMessage = `## UPDATE: Sibling ${finishedDisplayNum} Completed Research\n\n${truncatedReport}`;
-        try {
-          await targetSession.steer(injectionMessage);
-        } catch (err) {
-          logger.warn(`[deep-research] Failed to inject findings from ${finished.id} into ${target.id}:`, err);
+      // Guard: if the LLM returned the full JSON envelope as its response text and JSON
+      // parsing failed upstream, finalReport.content may be the raw JSON string rather
+      // than the extracted markdown. Unwrap it here so docs never show the raw JSON.
+      try {
+        const parsed: unknown = JSON.parse(result);
+        if (parsed && typeof parsed === 'object' && typeof (parsed as Record<string, unknown>)['content'] === 'string') {
+          result = (parsed as Record<string, unknown>)['content'] as string;
         }
-      }
-    }
-  }
-
-  private async handleSiblingCompletion(_finished: ResearchSibling, signal?: AbortSignal) {
-    if (signal?.aborted) return;
-    if (this.state.promotedId || this.state.finalSynthesis) return;
-
-    const currentRound = this.state.currentRound;
-    const roundAspects = Object.values(this.state.aspects).filter(a => a.id.startsWith(`${currentRound}.`));
-    const allCompletedWithReports = roundAspects.filter(a => a.status === 'completed' && a.report);
-
-    if (allCompletedWithReports.length === 0) {
-      const allFailed = roundAspects.filter(a => a.status === 'failed');
-      const errors = allFailed.map(a => `• Researcher ${getDisplayNumber(this.state, a.id)}: ${a.error}`).join('\n');
-      this.rejectCompletion(new Error(`Research failed. All researchers encountered errors:\n\n${errors}`));
-      return;
-    }
-
-    await this.runCoordinatorEval(signal);
-  }
-
-  private async runCoordinatorEval(signal?: AbortSignal) {
-    const evaluatedRound = this.state.currentRound;
-    const coordId = `coord.${evaluatedRound}`;
-
-    // Add evaluator slice AFTER all previous round slices are complete (grey)
-    // The evaluator does not count toward the 3 max concurrent researchers limit
-    addSlice(this.options.panelState, coordId, 'Eval', false);
-    activateSlice(this.options.panelState, coordId);
-    this.options.onUpdate();
-
-    // An agenda item leaves remainingAgenda once assigned to a non-failed aspect.
-    // - pending/running/completed: considered in-progress or done — drop from list
-    // - failed: NOT excluded — evaluator must be able to re-delegate failed topics
-    // This also fixes orphaned items (beyond initialCount): they remain visible until
-    // the evaluator delegates them as exact-string queries, at which point they become
-    // pending aspects and drop off.
-    const assignedAspectQueries = new Set(
-      Object.values(this.state.aspects)
-        .filter(a => a.status !== 'failed')
-        .map(a => a.query)
-    );
-    const remainingAgenda = this.state.initialAgenda.filter(q => !assignedAspectQueries.has(q));
-    const targetRounds = this.getMaxRounds(this.state.complexity);
-    const hardLimit = targetRounds + MAX_EXTRA_ROUNDS;
-    const isAtTarget = this.state.currentRound >= targetRounds;
-    const isAtHardLimit = this.state.currentRound >= hardLimit;
-
-    // Provide ALL completed findings (including the lead's own) — fresh context via complete()
-    // This includes ALL researchers from ALL rounds that have completed with reports
-    const allCompleted = Object.values(this.state.aspects).filter(a => a.status === 'completed' && a.report);
-    
-    logger.log(`[deep-research] Evaluator Round ${evaluatedRound}: Analyzing ${allCompleted.length} completed researchers from all rounds`);
-    
-    const allReportsContext = allCompleted.length > 0
-      ? `## All Research Findings:\n\n` +
-        allCompleted.map(a => {
-          const report = a.report || '';
-          const truncated = truncatePreservingLinks(report, MAX_EVALUATOR_REPORT_LENGTH);
-          const roundNum = a.id.split('.')[0] ?? '?';
-          return `### Researcher ${getDisplayNumber(this.state, a.id)} (Round ${roundNum}): ${a.query}\n${truncated}`;
-        }).join('\n\n---\n\n')
-      : '';
-
-    const leadPromptRaw = readFileSync(join(__dirname, '..', 'prompts', 'system-lead-evaluator.md'), 'utf-8');
-    const originalAgendaStr = this.state.initialAgenda.map(q => `• ${q}`).join('\n');
-    let leadPrompt = leadPromptRaw
-      .replace('{ROOT_QUERY}', this.state.rootQuery)
-      .replace('{ORIGINAL_AGENDA}', originalAgendaStr)
-      .replace('{ROUND_NUMBER}', this.state.currentRound.toString())
-      .replace('{MAX_ROUNDS}', targetRounds.toString());
-
-    if (isAtHardLimit) {
-      leadPrompt += '\n\n⚠️ **CRITICAL: ABSOLUTE MAXIMUM REACHED.** You MUST provide a FINAL SYNTHESIS in Markdown format. Do NOT return a JSON delegation object.';
-    } else if (isAtTarget) {
-      leadPrompt += '\n\n⚠️ **NOTICE: TARGET DEPTH REACHED.** Synthesize if the agenda is substantially covered. Only delegate if CRITICAL GAPS remain unexplored.';
-    }
-
-    const agendaSection = remainingAgenda.length > 0
-      ? `\n### Unfulfilled Agenda Items\n${remainingAgenda.map(q => `- ${q}`).join('\n')}`
-      : '\n### All Agenda Items Covered\nAll initial research agenda items have been addressed.';
+      } catch { /* result is not JSON — use as-is */ }
 
-    const promotionPrompt = leadPrompt + '\n\n' + allReportsContext + agendaSection;
+      // Final post-processing: Ensure CITED LINKS section is accurate and consistent
+      const synthesisService = await getService<IResearchSynthesisService>(ServiceNames.RESEARCH_SYNTHESIS_SERVICE, ctx, container);
+      result = synthesisService.ensureCitedLinks(researchId, result);
 
-    try {
-      this.updateState({ type: 'PROMOTION_STARTED', id: coordId });
+      // Append steering guidance — all consumed messages throughout the session
+      const finalSteeringMessages = getActiveSteeringMessages(this.options.sessionId);
+      if (finalSteeringMessages.length > 0) {
+          logger.debug(`[DeepOrchestrator] Appending guidance from ${finalSteeringMessages.length} steering messages to final report`);
+          result = synthesisService.appendSteeringGuidance(result, finalSteeringMessages);
+      }
 
-      const auth = await this.options.ctx.modelRegistry.getApiKeyAndHeaders(this.options.model);
-      if (!auth.ok) throw new Error(`Failed to get API credentials: ${auth.error}`);
+      // NOTE: Model metadata (appendMetadata) is now applied at the very end
+      // of the result chain in research-tool-definition.ts (or sdk.ts for SDK
+      // users) so it always appears after metrics/summaries.
 
-      const heartbeat = setInterval(() => this.options.onUpdate(), 500);
-      let response: Awaited<ReturnType<typeof complete>>;
+      const sessionDuration = Date.now() - this.sessionStart;
+      metrics.observe('research_session_duration_ms', sessionDuration, { mode: 'deep', complexity: String(complexity), status: 'success' });
+      
+      // Fire onComplete observer event. A throwing user observer must NOT divert
+      // control into the catch below — that would fire onComplete AGAIN with a
+      // fallback payload (double terminal callback) AND silently replace the
+      // full report with the fallback synthesis. Isolate it, mirroring the
+      // researcher-executor's safeObserve pattern.
       try {
-        response = await complete(this.options.model, {
-          messages: [{ role: 'user', content: [{ type: 'text', text: promotionPrompt }], timestamp: Date.now() }]
-        }, { apiKey: auth.apiKey!, headers: auth.headers, signal });
-      } finally {
-        clearInterval(heartbeat);
+        observer?.onComplete?.(result);
+      } catch (obsErr) {
+        logger.debug('[DeepOrchestrator] onComplete observer threw:', obsErr);
       }
 
-      const decision = response.content
-        .filter((c): c is TextContentBlock => isTextContentBlock(c))
-        .map(c => c.text)
-        .join('');
-      const usage = parseTokenUsage(response.usage);
-      const tokens = calculateTotalTokens(usage);
-      const cost = this.calculateUsageCost(usage);
-      if (tokens > 0) {
-        this.options.onTokens(tokens);
-        updateSliceTokens(this.options.panelState, coordId, tokens, cost);
-      }
+      return result;
 
-      const evalDecision = parseEvaluatorResponse(decision);
-
-      logger.log(`[deep-research] Evaluator decision for Round ${evaluatedRound}: ${
-        evalDecision.action === 'synthesize'
-          ? 'SYNTHESIS - completing research'
-          : `DELEGATION - spawning ${evalDecision.queries.length} new researchers in Round ${evaluatedRound + 1}`
-      }`);
-
-      this.updateState({
-        type: 'PROMOTION_DECISION',
-        finalSynthesis: evalDecision.action === 'synthesize' ? evalDecision.content : undefined,
-        nextQueries: evalDecision.action === 'delegate' ? evalDecision.queries : [],
-        maxRounds: hardLimit
-      });
-
-      // Credit the evaluator work using the round number captured BEFORE the state transition
-      if (this.options.panelState.progress) {
-        const evalKey = `eval.${evaluatedRound}`;
-        if (!this.progressCredits.has(evalKey)) {
-          this.options.panelState.progress.made += DeepResearchOrchestrator.LEAD_EVAL_UNITS;
-          this.progressCredits.set(evalKey, DeepResearchOrchestrator.LEAD_EVAL_UNITS);
-        }
-        // Extend the progress budget if the evaluator spawned a new round
-        if (evalDecision.action === 'delegate' && evalDecision.queries.length > 0) {
-          this.options.panelState.progress.expected +=
-            evalDecision.queries.length * DeepResearchOrchestrator.UNITS_PER_RESEARCHER
-            + DeepResearchOrchestrator.LEAD_EVAL_UNITS;
-        }
+    } catch (error) {
+      const sessionDuration = Date.now() - this.sessionStart;
+      const aborted = signal?.aborted === true;
+      metrics.observe('research_session_duration_ms', sessionDuration, { mode: 'deep', complexity: String(complexity), status: aborted ? 'cancelled' : 'error' });
+      // A user cancellation is a clean stop, not an error — log it at debug so a
+      // quit-mid-run doesn't surface a red error line that reads like a failure.
+      if (aborted) {
+        logger.debug(`[DeepOrchestrator] Research cancelled: ${error instanceof Error ? error.message : String(error)}`);
+      } else {
+        logger.error(`[DeepOrchestrator] Research failed: ${error instanceof Error ? error.message : String(error)}`);
       }
 
-      completeSlice(this.options.panelState, coordId);
-      this.options.onUpdate();
-
-      // CRITICAL: Must trigger next step after evaluator completes
-      // The evaluator does NOT run through executeSibling(), so there's no
-      // finally block to call startRound(). We must call it explicitly.
-      
-      // Give state a moment to propagate the update
-      await new Promise(resolve => setTimeout(resolve, STATE_PROPAGATION_DELAY_MS));
-      
-      if (evalDecision.action === 'synthesize') {
-        logger.log('[deep-research] Evaluator chose SYNTHESIS - resolving research');
-        if (evalDecision.content) {
-          this.resolveResult(evalDecision.content);
-        } else {
-          logger.error('[deep-research] Evaluator synthesis was empty - falling back to historical findings');
-          this.resolveResult(this.buildAllFindingsContext());
+      // Terminal-callback contract (shared with QuickResearchOrchestrator): fire
+      // EXACTLY ONE of onComplete / onError. A returned report — full above, or a
+      // partial fallback synthesised from whatever was collected (the natural
+      // outcome of a mid-run cancel) — is a completion (onComplete). Only a run
+      // with nothing to return is a failure (onError + throw). Previously this
+      // fired onError AND THEN onComplete on the fallback path, signalling both
+      // "errored" and "completed" for one run.
+      try {
+        const synthesisService = await getService<IResearchSynthesisService>(ServiceNames.RESEARCH_SYNTHESIS_SERVICE, ctx, container);
+        if (synthesisService.hasReports(researchId)) {
+          let fallback = synthesisService.buildFallbackSynthesis(researchId, this.currentRound);
+          fallback = synthesisService.ensureCitedLinks(researchId, fallback);
+          logger.log(`[DeepOrchestrator] Returning ${aborted ? 'partial (cancelled)' : 'fallback'} synthesis (${fallback.length} chars) from ${synthesisService.getReportCount(researchId)} collected reports`);
+          const finalSteeringMessages = getActiveSteeringMessages(this.options.sessionId);
+          const result = synthesisService.appendSteeringGuidance(fallback, finalSteeringMessages);
+          try {
+            observer?.onComplete?.(result);
+          } catch (obsErr) {
+            logger.debug('[DeepOrchestrator] fallback onComplete observer threw:', obsErr);
+          }
+          return result;
         }
-      } else if (isAtHardLimit) {
-        // Evaluator returned delegation despite the mandatory synthesis instruction.
-        // Enforce completion by falling back to concatenated researcher findings.
-        logger.warn('[deep-research] Evaluator returned delegation at hard limit — forcing synthesis from findings');
-        this.resolveResult(this.buildAllFindingsContext());
-      } else {
-        // Evaluator delegated more researchers - start next round
-        logger.log(`[deep-research] Evaluator chose DELEGATION - starting Round ${evaluatedRound + 1}`);
-        await this.startRound(signal);
+      } catch (fallbackErr) {
+        logger.warn(`[DeepOrchestrator] Fallback synthesis also failed:`, fallbackErr);
       }
 
-    } catch (err) {
-      const error = err instanceof Error ? err : new Error(String(err));
-      logger.error(`[deep-research] Coordinator evaluation failed for round ${evaluatedRound}:`, error);
-      this.rejectCompletion(error);
-    }
-  }
-
-  private buildRoleContext(aspect: ResearchSibling, roleContext: ReturnType<typeof getResearcherRoleContext>): string {
-    const { displayNumber, roundNumber, totalInRound } = roleContext;
-    const siblingNumInRound = parseInt(aspect.id.split('.')[1] ?? '1');
-    return `## Your Role
-
-You are **Researcher ${displayNumber}** (${siblingNumInRound} of ${totalInRound} in Round ${roundNumber}).
-- **Topic**: ${aspect.query}
-- **Round**: ${roundNumber} of ${this.getMaxRounds(this.state.complexity)}
-- **Tool Usage**: 4 gathering calls + up to 3 context-gated scrape batches (Batch 1 ≤3 URLs, Batch 2 ≤2 URLs, Batch 3 ≤3 URLs)`;
-  }
-
-  private buildAllFindingsContext(): string {
-    const allCompleted = Object.values(this.state.aspects)
-      .filter(a => a.status === 'completed' && a.report)
-      .sort((a, b) => {
-        const aRound = parseInt(a.id.split('.')[0] ?? '0');
-        const bRound = parseInt(b.id.split('.')[0] ?? '0');
-        if (aRound !== bRound) return aRound - bRound;
-        const aNum = parseInt(a.id.split('.')[1] ?? '0');
-        const bNum = parseInt(b.id.split('.')[1] ?? '0');
-        return aNum - bNum;
-      });
-
-    if (allCompleted.length === 0) {
-      return '## Research Findings So Far\n\n*No earlier researchers have completed their findings yet.*';
-    }
-
-    let output = '## Research Findings So Far\n\n';
-    let currentRoundNum = 0;
-
-    for (const completed of allCompleted) {
-      const round = parseInt(completed.id.split('.')[0] ?? '0');
-      if (round !== currentRoundNum) {
-        currentRoundNum = round;
-        output += `\n### Round ${round}\n\n`;
+      // Nothing to return — this run genuinely failed (or was cancelled with no
+      // collected work). Fire onError and propagate, matching QuickOrchestrator.
+      try {
+        observer?.onError?.(error instanceof Error ? error : new Error(String(error)));
+      } catch (obsErr) {
+        logger.debug('[DeepOrchestrator] onError observer threw:', obsErr);
+      }
+      throw error;
+    } finally {
+      // Guard cleanup: getOrchestrationService()/cleanup can throw when the
+      // container is disposing (e.g. SIGTERM mid-run). An unguarded throw here
+      // would replace the in-flight error or discard a successful return value.
+      // Mirrors QuickResearchOrchestrator's guarded cleanup.
+      try {
+        const orch = await this.getOrchestrationService();
+        // On user abort, skip the post-run FTS rebuild + optimize: they are
+        // non-signal-aware optimization passes (durability lives in the LanceDB
+        // commits already made) and would block Esc from returning promptly.
+        // Any rows the run committed are picked up by the next run's start-of-run
+        // cleanup (which performs the same rebuild) or the next completed run.
+        await orch.cleanupResearchServices(undefined, researchId, ctx, this.config,
+          { skipStoreMaintenance: signal?.aborted === true });
+      } catch (cleanupErr) {
+        logger.warn('[DeepOrchestrator] Failed to cleanup research services:', cleanupErr);
       }
-      const displayNum = getDisplayNumber(this.state, completed.id);
-      const report = completed.report || '';
-      const truncatedReport = truncatePreservingLinks(report, MAX_EVALUATOR_REPORT_LENGTH);
-        
-      output += `#### Researcher ${displayNum}: ${completed.query}\n\n${truncatedReport}\n\n`;
     }
-
-    return output;
   }
 }