@lincoln504/pi-research 0.1.12 → 1.0.0

package/src/core/planning-utils.ts

@@ -0,0 +1,299 @@
+/**
+ * Planning Utilities
+ *
+ * Helper functions for planning service
+ */
+
+import { logger } from '../logger.ts';
+import { Value } from 'typebox/value';
+import { extractJson } from '../utils/json-utils.ts';
+import type { ResearchPlan, ResearcherConfig } from './interfaces/planning-interfaces.ts';
+import { ResearchPlanSchema } from './interfaces/planning-interfaces.ts';
+import {
+  MAX_TEAM_SIZE_LEVEL_1,
+  MAX_TEAM_SIZE_LEVEL_2,
+  MAX_TEAM_SIZE_LEVEL_3,
+  MAX_ROUNDS_LEVEL_1,
+  MAX_ROUNDS_LEVEL_2,
+  MAX_ROUNDS_LEVEL_3,
+  MAX_QUERIES_PER_RESEARCHER_LEVEL_1,
+  MAX_QUERIES_PER_RESEARCHER_LEVEL_2,
+  MAX_QUERIES_PER_RESEARCHER_LEVEL_3,
+} from '../constants.ts';
+
+/**
+ * Get the max team size for a complexity level
+ */
+export function getTeamSize(complexity: 1 | 2 | 3): number {
+  return complexity === 1 ? MAX_TEAM_SIZE_LEVEL_1
+    : complexity === 2 ? MAX_TEAM_SIZE_LEVEL_2
+    : MAX_TEAM_SIZE_LEVEL_3;
+}
+
+/**
+ * Get the query budget per researcher for a complexity level
+ */
+export function getQueryBudget(complexity: 1 | 2 | 3): number {
+  return complexity === 1 ? MAX_QUERIES_PER_RESEARCHER_LEVEL_1
+    : complexity === 2 ? MAX_QUERIES_PER_RESEARCHER_LEVEL_2
+    : MAX_QUERIES_PER_RESEARCHER_LEVEL_3;
+}
+
+/**
+ * Get the max rounds for a complexity level
+ */
+export function getMaxRounds(complexity: 1 | 2 | 3): number {
+  return complexity === 1 ? MAX_ROUNDS_LEVEL_1
+    : complexity === 2 ? MAX_ROUNDS_LEVEL_2
+    : MAX_ROUNDS_LEVEL_3;
+}
+
+/**
+ * Get complexity-specific guidance for the coordinator
+ */
+export function getComplexityGuidance(complexity: 1 | 2 | 3, maxTeamSize: number, queryBudget: number): string {
+  if (complexity === 1) {
+    return '**Complexity: Level 1 (Normal)**. Conduct a thorough, well-rounded investigation of the topic covering the primary angles with adequate citations. **Plan ONLY Round 1** — a single comprehensive round. **Default to a single researcher** for most Level 1 topics — one focused researcher can handle the majority of normal-complexity queries efficiently. Use 2 researchers only when the topic clearly spans two distinct, non-overlapping domains that benefit from parallel investigation. This is a ONE-SHOT effort: plan Round 1 as if it is the only round, because it should be. Only Level 2 or Level 3 research should involve multiple rounds.';
+  } else if (complexity === 2) {
+    return `**Complexity: Level 2 (Deep)**. **ONLY for HIGH/EXTREME research needs.** Level 2 should be reserved for topics that clearly require deeper investigation than a single comprehensive round can provide. **Plan ONLY Round 1** — a thorough, well-structured first round. Subsequent rounds are reactive and only delegated when Round 1 findings reveal clear gaps that warrant deeper or broader coverage. Do not pre-plan multiple rounds; delegate follow-ups only when Round 1 demonstrates genuine need.
+
+Scale your team (1-${maxTeamSize}) based on topic scope — not every round needs the full team. A single well-targeted researcher for follow-up gaps is usually sufficient.`;
+  } else {
+    return `**Complexity: Level 3 (Ultra)**. Perform an exhaustive, deep-dive research effort, leaving no stone unturned. **Plan ONLY Round 1** — make it comprehensive, deploying up to ${maxTeamSize} researchers with full query budgets (${queryBudget} each) covering all major dimensions of the topic. Round 1 should aim to cover the full scope comprehensively.
+
+Rounds 2-3 are purely reactive — they only happen when Round 1 findings reveal gaps that warrant deeper diving into specific dimensions or broader exploration of adjacent topics. Do NOT pre-plan multiple rounds; let the findings drive the need. Think of Round 1 as the comprehensive landscape map, with follow-up rounds as targeted expeditions into areas that need more detail.
+
+**ULTRA-SPECIFICITY MANDATE**: Level 3 demands granular, exhaustive detail on every fact that benefits from it — exact figures, dates, names, mechanisms, edge cases, historical context, technical specifics, and primary-source precision. Plan dedicated researchers for drilling into the ultra-specific dimensions of any finding where greater detail adds value.`;
+  }
+}
+
+/**
+ * Get complexity-specific guidance for the evaluator
+ */
+export function getEvaluatorComplexityGuidance(complexity: 1 | 2 | 3): string {
+  if (complexity === 1) {
+    return `**Level 1 (Normal)** - Thorough, well-rounded investigation with solid multi-source coverage.
+
+- **SYNTHESIZE when**: The primary topic is covered from multiple angles with evidence from diverse sources and no significant gaps remain that would prevent a complete answer.
+- **DELEGATE when**: Coverage is incomplete, important angles are missing, or additional sources would meaningfully strengthen the findings.
+
+**DEFAULT PATH**: Synthesize after Round 1 if the researcher produced solid coverage of the core topic. **Level 1 should almost always be a single round** — only delegate a second round when Round 1 clearly missed important angles or lacks source diversity. A single researcher is the default for Level 1 follow-up rounds — only use 2 researchers if the remaining gaps clearly span two distinct domains. Level 2 research escalation should be reserved for truly high/extreme research needs only.`;
+  } else if (complexity === 2) {
+    return `**Level 2 (Deep)** - Thorough, multi-phase investigation with comprehensive citations.
+
+- **SYNTHESIZE when**: You are confident the research is genuinely complete. This means multiple angles covered with substantial findings across all major topics, diverse sources cited throughout, and no significant gaps in coverage.
+- **DELEGATE when**: ANY gaps remain in major topics, insufficient source diversity, missing details, or areas that need deeper exploration. Don't synthesize prematurely.
+
+**DEFAULT PATH: When in doubt, DELEGATE**. It is better to conduct additional research rounds than to synthesize with incomplete findings. Level 2 is designed for multi-round research. Each round adds depth and citation diversity — but do not delegate unnecessarily. Synthesize after Round 1 ONLY if the researcher produced comprehensive coverage of the topic with good source diversity. If Round 1 has any gaps, delegate Round 2. A third round is only warranted when Round 2 still leaves significant holes. Scale researcher count to match the gaps — focused gaps may only need 1 researcher, while broad gaps benefit from the full team.`;
+  } else {
+    return `**Level 3 (Ultra)** - Exhaustive, comprehensive deep-dive with extensive citations.
+
+- **SYNTHESIZE when**: You are confident the research is genuinely and exhaustively complete. This means exhaustively covered across ALL substantial avenues with multiple diverse sources per major topic, comprehensive citations throughout, and no meaningful gaps remain.
+- **DELEGATE when**: ANY meaningful gaps, nuanced angles, insufficient source diversity, inadequate citations, or areas needing deeper investigation remain.
+
+**DEFAULT PATH: When in doubt, DELEGATE**. It is better to conduct additional research rounds than to synthesize with incomplete findings. Level 3 has ${MAX_ROUNDS_LEVEL_3} rounds available. Be generous with follow-up delegation — lean toward using all available rounds. Each round adds breadth, depth, and citation diversity. Delegate for follow-up whenever remaining gaps or under-explored angles exist, even if progress has been good. Only synthesize when you have genuinely comprehensive coverage across all major areas with no meaningful gaps that another round would address.
+
+**ULTRA-SPECIFICITY MANDATE**: For every fact, finding, or topic area where greater granularity adds value, delegate additional researchers to pursue it. This includes: exact figures and statistics, precise dates and timelines, technical mechanisms, named individuals and their specific contributions, primary-source verbatim data, edge cases, and any dimension where surface-level coverage would leave the reader with unanswered questions.`;
+  }
+}
+
+/**
+ * Get round phase guidance based on current round and max rounds
+ */
+export function getRoundPhaseGuidance(currentRound: number, maxRounds: number, complexity: 1 | 2 | 3, maxTeamSize: number): string {
+  const roundRatio = currentRound / maxRounds;
+
+  if (roundRatio <= 0.5) {
+    // Early rounds
+    if (complexity === 3) {
+      return `\n\n---\n\n**Round Phase: EARLY (Round ${currentRound} of ${maxRounds}) — Level 3 Ultra**\n\n**DELEGATE. Do not synthesize.** You are in the early phase of an exhaustive research effort with ${maxRounds} rounds available.\n- Deploy up to ${maxTeamSize} researchers across completely distinct angles — leave no major dimension unmapped\n- Not every round needs all ${maxTeamSize} researchers — use as many as the remaining gaps require\n- Fully saturate each researcher's query budget; partial budgets waste available depth\n- This phase exists to establish the broadest possible foundation of sources and findings\n- Do NOT synthesize under any circumstances this early`;
+    }
+    // Level 1 / Level 2 early
+    return `\n\n---\n\n**Round Phase: EARLY (Round ${currentRound} of ${maxRounds})**\n\nYou are in the early phase of research. Be more permissive with delegation:\n- Deploy researchers to broadly map the landscape\n- Not every round needs all ${maxTeamSize} researchers — use as many as the remaining gaps require\n- Don't worry if findings are incomplete — later rounds can fill gaps\n- Focus on breadth and initial exploration\n- Use available researchers to cover distinct angles in parallel`;
+  } else if (roundRatio <= 0.8) {
+    // Middle rounds
+    if (complexity === 3) {
+      return `\n\n---\n\n**Round Phase: MIDDLE (Round ${currentRound} of ${maxRounds}) — Level 3 Ultra**\n\n**PREFER DELEGATION.** You are in the middle phase of exhaustive research — use your remaining rounds.\n- Not every round needs all ${maxTeamSize} researchers — use as many as the remaining gaps require\n- With ${maxRounds - currentRound} round(s) remaining, delegate to cover angles not yet fully explored, drill into deeper sub-topics, or verify findings with additional sources\n- Be generous with follow-up — delegate whenever gaps or under-explored angles exist\n- Synthesize ONLY when you genuinely cannot identify gaps that another round would address\n- If you can name even one meaningful unexplored angle — DELEGATE`;
+    }
+    if (complexity === 2) {
+      return `\n\n---\n\n**Round Phase: MIDDLE (Round ${currentRound} of ${maxRounds})**\n\n**Level 2 (Deep) Guidance**: You are in the middle phase of deep research. Continue delegating when there are still meaningful gaps or areas to explore.\n\n- Not every round needs all ${maxTeamSize} researchers — use as many as the remaining gaps require\n- Synthesize only when findings are comprehensive and no significant gaps remain that warrant another round\n- Default to delegating when in doubt\n\n`;
+    }
+    // Level 1 middle
+    return `\n\n---\n\n**Round Phase: MIDDLE (Round ${currentRound} of ${maxRounds})**\n\nYou are in the middle phase of research. Apply balanced judgment:\n- Not every round needs all ${maxTeamSize} researchers — use as many as the remaining gaps require\n- Synthesize if you have substantial coverage of the key aspects\n- Delegate for significant gaps or to explore specialized sub-topics\n- Consider depth over breadth at this stage\n- Focus on rounding out incomplete areas`;
+  } else {
+    // Late rounds
+    if (complexity === 3) {
+      return `\n\n---\n\n**Round Phase: LATE (Round ${currentRound} of ${maxRounds}) — Level 3 Ultra**\n\nYou are in the late phase of exhaustive research. Still prefer delegation — use your remaining rounds.\n- Not every round needs all ${maxTeamSize} researchers — use as many as the remaining gaps require\n- Delegate if ANY meaningful dimension remains under-sourced, under-verified, or shallowly covered\n- Use remaining rounds to drill into specialist detail, verify findings, or explore nuanced angles surfaced by earlier rounds\n- Synthesize only when you have genuinely exhausted meaningful research avenues AND have comprehensive multi-source coverage across all major areas`;
+    }
+    // Level 1 / Level 2 late
+    return `
+
+---
+
+**Round Phase: LATE (Round ${currentRound} of ${maxRounds})**
+
+You are in the late phase of research. Set a higher threshold for delegation:
+- Not every round needs all ${maxTeamSize} researchers — use as many as the remaining gaps require\n- Synthesize if the core question is answerable with current findings
+- Delegate only for CRITICAL gaps that cannot be resolved from existing findings
+- Avoid delegating for minor details or marginal improvements
+- Focus on delivering a complete, coherent response`;
+  }
+}
+
+/**
+ * Parse JSON from LLM response into ResearchPlan
+ */
+export function parseJsonPlan(text: string): ResearchPlan {
+  const result = extractJson<unknown>(text, 'object');
+  if (!result.success || !result.value) {
+    const preview = text.length > 100 ? text.slice(0, 100) + '...' : text;
+    throw new Error(`Failed to extract valid JSON plan: ${result.error}. Raw response preview: "${preview}"`);
+  }
+
+  // Robust validation using TypeBox
+  try {
+    // 1. Convert/Coerce values (e.g. string numbers to numbers, single values to arrays if possible)
+    const coerced = Value.Convert(ResearchPlanSchema, result.value);
+    
+    // 2. Validate against schema
+    if (!Value.Check(ResearchPlanSchema, coerced)) {
+      const errors = [...Value.Errors(ResearchPlanSchema, coerced)];
+      const errorMsg = errors.map((e: any) => `${e.path}: ${e.message}`).join(', ');
+      // If validation fails, we throw to satisfy tests and ensure system integrity
+      throw new Error(`Plan validation failed: ${errorMsg}`);
+    }
+
+    const plan = coerced as ResearchPlan;
+
+    // Invariant: only a 'synthesize' response may omit researchers. Every other action
+    // (delegate, or an unset action that defaults to delegation downstream) must carry a
+    // researchers array to act on. The schema relaxes `researchers` to optional so a valid
+    // synthesis ({ action, content }) is accepted instead of being thrown into the costly
+    // agentic-repair path; this guard preserves the delegate-must-have-researchers rule.
+    if (plan.action !== 'synthesize' && plan.researchers === undefined) {
+      throw new Error('Plan validation failed: /researchers: a non-synthesize plan must include a researchers array');
+    }
+
+    // 3. Post-processing
+    if (plan.researchers) {
+      plan.researchers.forEach((r) => {
+        // Coerce IDs to strings for consistency
+        r.id = String(r.id);
+      });
+    }
+
+    return plan;
+  } catch (err) {
+    const msg = err instanceof Error ? err.message : String(err);
+    throw new Error(`Plan validation error: ${msg}`, { cause: err });
+  }
+}
+
+/**
+ * Build a fallback coordinator plan when LLM fails
+ */
+export function buildFallbackCoordinatorPlan(serviceName: string, _rawText: string, query: string): ResearchPlan {
+  const words = query.split(/\s+/).slice(0, 6).join(' ');
+  const queries = [query, `${words} overview`, `${words} latest`].filter(Boolean).slice(0, 3);
+  logger.warn(`[${serviceName}] Coordinator fallback: single researcher for "${query.slice(0, 80)}"`);
+  return {
+    action: 'delegate',
+    researchers: [{ id: '1', name: 'General Researcher', goal: `Research the following query comprehensively: ${query}`, queries }],
+    allQueries: queries,
+  };
+}
+
+/**
+ * Cap researcher queries to stay within budget
+ */
+export function capResearcherQueries(plan: ResearchPlan, complexity: 1 | 2 | 3, serviceName: string): ResearchPlan {
+  const budget = getQueryBudget(complexity);
+
+  // Hard caps per round - based on actual maximum possible queries
+  // Level 1: 2 researchers x 10 queries = 20 maximum
+  // Level 2: 3 researchers x 15 queries = 45 maximum
+  // Level 3: 5 researchers x 20 queries = 100 maximum
+  const ROUND_HARD_CAP = complexity === 1 ? 20
+    : complexity === 2 ? 45
+    : 100;
+
+  if (!plan.researchers) return plan;
+
+  // 1. Normalize IDs to strings and cap individual researchers
+  // CRITICAL: Only keep researchers with non-empty queries to guarantee search results
+  const maxTeam = getTeamSize(complexity);
+  plan.researchers = plan.researchers
+    .filter(r => r && typeof r === 'object' && Array.isArray(r.queries) && r.queries.length > 0)
+    .slice(0, maxTeam)
+    .map(r => {
+      const normalized = { ...r, id: String(r.id) };
+      if (normalized.queries.length > budget) {
+        logger.warn(`[${serviceName}] Capping researcher ${normalized.id} queries: ${normalized.queries.length} → ${budget}`);
+        normalized.queries = normalized.queries.slice(0, budget);
+      }
+      return normalized;
+    });
+
+  // 1b. Enforce unique researcher IDs within the round. Reports are keyed `${round}.${id}`
+  // and search links by String(id); two researchers sharing an id (the LLM emitting `1.1`
+  // twice, or `1` and "1") collide last-writer-wins — both run but one's findings are silently
+  // dropped. Renumber collisions so every launched researcher's report is retained.
+  const seenIds = new Set<string>();
+  for (const r of plan.researchers) {
+    const rid = String(r.id);
+    if (!seenIds.has(rid)) { seenIds.add(rid); continue; }
+    let n = 2;
+    let candidate = `${rid}-${n}`;
+    while (seenIds.has(candidate)) { n++; candidate = `${rid}-${n}`; }
+    logger.warn(`[${serviceName}] Duplicate researcher id '${rid}' → renumbered '${candidate}'`);
+    r.id = candidate;
+    seenIds.add(candidate);
+  }
+
+  // 2. Enforce global round budget
+  let totalQueries = plan.researchers.reduce((sum, r) => sum + r.queries.length, 0);
+  if (totalQueries > ROUND_HARD_CAP) {
+    logger.warn(`[${serviceName}] Total round queries (${totalQueries}) exceeds hard cap (${ROUND_HARD_CAP}). Trimming...`);
+    while (totalQueries > ROUND_HARD_CAP) {
+      let maxCount = 0;
+      let maxIdx = -1;
+      if (!plan.researchers) break;
+      for (let i = 0; i < plan.researchers.length; i++) {
+        if (plan.researchers[i]!.queries.length > maxCount) {
+          maxCount = plan.researchers[i]!.queries.length;
+          maxIdx = i;
+        }
+      }
+      if (maxIdx === -1) break;
+      plan.researchers[maxIdx]!.queries.pop();
+      totalQueries--;
+    }
+  }
+
+  plan.allQueries = plan.researchers.flatMap(r => r.queries);
+
+  // If no researchers remain with valid queries, force synthesis
+  if (plan.action === 'delegate' && plan.researchers.length === 0) {
+    logger.warn(`[${serviceName}] No valid researchers after query cap/filtering, forcing synthesize`);
+    return { ...plan, action: 'synthesize', researchers: [], allQueries: [] };
+  }
+
+  return plan;
+}
+
+/**
+ * Generate researcher configurations from a plan
+ */
+export function generateResearchers(plan: ResearchPlan, _query: string, _complexity: 1 | 2 | 3): ResearcherConfig[] {
+  if (!plan.researchers) {
+    return [];
+  }
+
+  // Normalize IDs to strings
+  const researchers = plan.researchers.map(r => ({
+    ...r,
+    id: String(r.id),
+  }));
+
+  return researchers;
+}

package/src/core/scheduler-factory.ts

@@ -0,0 +1,48 @@
+/**
+ * Scheduler Factory Interface
+ *
+ * Defines the contract for creating scheduler instances.
+ * This interface lives in the Core layer to follow Clean Architecture principles.
+ *
+ * Implementations should be provided by the Infrastructure layer.
+ */
+
+import type { Config } from '../config.ts';
+import type { IService } from './service-registry.ts';
+import type { IScheduler } from './interfaces/scheduler-interfaces.ts';
+export type { IScheduler };
+
+/**
+ * Scheduler Factory Interface
+ *
+ * Provides methods for creating and managing scheduler instances.
+ * This interface allows the Core layer to depend on abstractions,
+ * not concrete implementations from the Infrastructure layer.
+ */
+export interface ISchedulerFactory extends IService {
+  /**
+   * Get or create a scheduler instance.
+   * Handles leader election and client/server mode switching.
+   *
+   * @param config Optional configuration
+   * @returns A scheduler instance
+   */
+  getScheduler(config?: Config): Promise<IScheduler>;
+
+  /**
+   * Get the current scheduler version string.
+   * The version is derived from the configuration and changes when config changes.
+   *
+   * @param config Optional configuration
+   * @returns The scheduler version string
+   */
+  getSchedulerVersion(config?: Config): string;
+
+  /**
+   * Force a restart of the scheduler by clearing the global cache and state.
+   * This should be called when configuration changes are detected.
+   *
+   * @param forceClearRemoteState Whether to force clear state from remote processes
+   */
+  forceSchedulerRestart(forceClearRemoteState?: boolean): Promise<void>;
+}

package/src/core/scheduler-service.ts

@@ -0,0 +1,123 @@
+/**
+ * Scheduler Service
+ *
+ * Coordinates the multi-process browser worker pool and task scheduling.
+ * Implements leader election to ensure only one browser pool is active.
+ */
+
+import { ServiceLifecycle } from './service-registry.ts';
+import { ServiceNames } from './service-interfaces.ts';
+import type { IScheduler, ISchedulerService, ISchedulerInternals, ISchedulerInstance } from './service-interfaces.ts';
+import { logger } from '../logger.ts';
+import { raceWithDeadline } from '../utils/safe-unref.ts';
+
+/**
+ * Scheduler Service Implementation
+ */
+export class SchedulerService implements ISchedulerService, ISchedulerInternals {
+  readonly name = ServiceNames.SCHEDULER;
+  lifecycle = ServiceLifecycle.UNINITIALIZED;
+
+  private scheduler: IScheduler | null = null;
+  private initializationPromise: Promise<IScheduler> | null = null;
+  private schedulerVersion: string | null = null;
+  private pendingShutdownPromise: Promise<void> | null = null;
+  private restartInProgress = false;
+
+  async initialize(): Promise<void> {
+    this.lifecycle = ServiceLifecycle.INITIALIZED;
+  }
+
+  async dispose(): Promise<void> {
+    if (this.lifecycle === ServiceLifecycle.DISPOSED) return;
+    this.lifecycle = ServiceLifecycle.DISPOSING;
+
+    // Invalidate any in-flight initialization FIRST: the scheduler factory
+    // re-checks this slot (its "superseded" guard) after every await point,
+    // so nulling it here makes a mid-election init shut down its
+    // freshly-created scheduler (closing its HTTP server) instead of
+    // installing it onto a disposed service where nothing would ever tear it
+    // down. Then await the in-flight init (bounded — the election can block
+    // up to ~60s on the browser-init lock) so its product is torn down
+    // before we report disposal complete. The expected outcome is a
+    // rejection ("Initialization superseded"); swallow it.
+    const inFlightInit = this.initializationPromise;
+    this.initializationPromise = null;
+    if (inFlightInit) {
+      try {
+        await raceWithDeadline(inFlightInit.then(() => undefined, () => undefined), 10000);
+      } catch {
+        /* raceWithDeadline only rejects if the promise rejects; already swallowed above */
+      }
+    }
+
+    if (this.scheduler) {
+      try {
+        await this.scheduler.shutdown();
+      } catch (err) {
+        logger.error('[SchedulerService] Error during scheduler shutdown:', err);
+      }
+      this.scheduler = null;
+    }
+    
+    this.lifecycle = ServiceLifecycle.DISPOSED;
+  }
+
+  /**
+   * Get the current scheduler instance if initialized
+   */
+  getScheduler(): IScheduler | null {
+    return this.scheduler;
+  }
+
+  /**
+   * Check if the scheduler is ready
+   */
+  isReady(): boolean {
+    return this.scheduler !== null;
+  }
+
+  // ============================================================================
+  // ISchedulerInternals Implementation
+  // ============================================================================
+
+  getSchedulerInstance(): ISchedulerInstance | null {
+    return this.scheduler as unknown as ISchedulerInstance | null;
+  }
+
+  setSchedulerInstance(instance: ISchedulerInstance | null): void {
+    this.scheduler = instance as unknown as IScheduler | null;
+  }
+
+  getSchedulerVersion(): string | null {
+    return this.schedulerVersion;
+  }
+
+  setSchedulerVersion(version: string | null): void {
+    this.schedulerVersion = version;
+  }
+
+  getSchedulerInitializationPromise(): Promise<ISchedulerInstance> | null {
+    return this.initializationPromise as unknown as Promise<ISchedulerInstance> | null;
+  }
+
+  setSchedulerInitializationPromise(promise: Promise<ISchedulerInstance> | null): void {
+    this.initializationPromise = promise as unknown as Promise<IScheduler> | null;
+  }
+
+  getPendingShutdownPromise(): Promise<void> | null {
+    return this.pendingShutdownPromise;
+  }
+
+  setPendingShutdownPromise(promise: Promise<void> | null): void {
+    this.pendingShutdownPromise = promise;
+  }
+
+  isSchedulerRestartInProgress(): boolean {
+    return this.restartInProgress;
+  }
+
+  setSchedulerRestartInProgress(inProgress: boolean): void {
+    this.restartInProgress = inProgress;
+  }
+}

package/src/core/service-initialization.ts

@@ -0,0 +1,194 @@
+/**
+ * Service Initialization Module
+ *
+ * This module registers all services with the service registry.
+ * This is the central place for service configuration and initialization.
+ */
+
+import { registerService, getService, disposeAllServices, type IService, getServiceContainer } from './service-registry.ts';
+import type { ServiceContainer } from './service-registry.ts';
+import { ServiceNames } from './service-interfaces.ts';
+import type { IStateManager } from './interfaces/state-manager-interfaces.ts';
+import { SchedulerService } from './scheduler-service.ts';
+import { HealthCheckService } from './health-check-service.ts';
+import { PlanningService } from './planning-service.ts';
+import { logger } from '../logger.ts';
+
+/**
+ * Register all core services with the service registry
+ */
+export function registerCoreServices(container: ServiceContainer = getServiceContainer()): void {
+  logger.debug('[ServiceInitialization] Registering core services...');
+
+  // Register Scheduler Service
+  registerService(
+    ServiceNames.SCHEDULER,
+    () => new SchedulerService(),
+    {
+      allowOverwrite: false,
+      enableLogging: true,
+    },
+    container
+  );
+
+  // Register Health Check Cache Service
+  registerService(
+    ServiceNames.HEALTH_CHECK_CACHE,
+    () => new HealthCheckService(),
+    {
+      allowOverwrite: false,
+      enableLogging: true,
+    },
+    container
+  );
+
+  // Register Planning Service
+  registerService(
+    ServiceNames.PLANNING,
+    () => new PlanningService(),
+    {
+      // (Planning must be available early — it is eager-initialized via the eagerServices list below.)
+      allowOverwrite: false,
+      enableLogging: true,
+    },
+    container
+  );
+
+  logger.debug('[ServiceInitialization] All core services registered');
+}
+
+/**
+ * Initialize all core services
+ * This is called early in the application startup
+ *
+ * @param ctx - Optional extension context to pass to services
+ * @param container - Service container instance
+ */
+export async function initializeCoreServices(ctx?: any, container: ServiceContainer = getServiceContainer()): Promise<{ success: boolean; initialized: string[]; failed: string[] }> {
+  logger.log('[ServiceInitialization] Initializing core services...');
+
+  const initialized: string[] = [];
+  const failed: string[] = [];
+
+  // Critical infrastructure services (always initialize early)
+  const criticalInfrastructure = [
+    { name: ServiceNames.METRICS, label: 'Metrics Service' },
+    { name: ServiceNames.PROCESS_LIFECYCLE, label: 'Process Lifecycle Service' },
+    { name: ServiceNames.STATE_PATH_CONFIGURATION, label: 'State Path Configuration' },
+    { name: ServiceNames.FILE_LOCK_SERVICE, label: 'File Lock Service' },
+    { name: ServiceNames.STATE_BACKUP_MANAGER, label: 'State Backup Manager' },
+    { name: ServiceNames.STATE_SESSION_MANAGER, label: 'State Session Manager' },
+    { name: ServiceNames.STATE_BROWSER_MANAGER, label: 'State Browser Manager' },
+    { name: ServiceNames.STATE_METRICS_COLLECTOR, label: 'State Metrics Collector' },
+    { name: ServiceNames.STATE_VALIDATOR, label: 'State Validator' },
+    { name: ServiceNames.GPU_RESOURCE_SERVICE, label: 'GPU Resource Service' },
+    { name: ServiceNames.STATE_MANAGER, label: 'State Manager Service' },
+    { name: ServiceNames.HEALTH_CHECK_CACHE, label: 'Health Check Cache Service' },
+    { name: ServiceNames.HEALTH_REGISTRY, label: 'Health Registry Service' },
+  ];
+
+  // Services requiring eager initialization — proactively getService'd below so
+  // they are constructed at startup rather than on first use.
+  const eagerServices = [
+    { name: ServiceNames.PLANNING, label: 'Planning Service' },
+  ];
+
+  // Lazy services (initialized on first use)
+  const lazyServices = [
+    ServiceNames.SCHEDULER,
+    ServiceNames.KNOWLEDGE_STORE,
+    ServiceNames.RESEARCH_ORCHESTRATION,
+    ServiceNames.WORKER_POOL_MANAGER,
+  ];
+
+  try {
+    // Initialize critical infrastructure services
+    logger.log('[ServiceInitialization] Initializing critical infrastructure services...');
+    for (const service of criticalInfrastructure) {
+      try {
+        logger.debug(`[ServiceInitialization] Initializing ${service.label}...`);
+        // getService will call initialize(ctx) if not already initialized
+        await getService<IService>(service.name, ctx, container);
+        initialized.push(service.label);
+        logger.debug(`[ServiceInitialization] ${service.label} initialized`);
+      } catch (err) {
+        const errorMsg = `${service.label} initialization failed`;
+        logger.error(`[ServiceInitialization] FAILED: ${errorMsg}:`, err);
+        failed.push(errorMsg);
+        // Continue with other services even if one fails
+      }
+    }
+
+    // Initialize eagerly-marked services
+    logger.log('[ServiceInitialization] Initializing eagerly-marked services...');
+    for (const service of eagerServices) {
+      try {
+        logger.debug(`[ServiceInitialization] Initializing ${service.label}...`);
+        await getService<IService>(service.name, ctx, container);
+        initialized.push(service.label);
+        logger.debug(`[ServiceInitialization] ${service.label} initialized`);
+      } catch (err) {
+        const errorMsg = `${service.label} initialization failed`;
+        logger.error(`[ServiceInitialization] FAILED: ${errorMsg}:`, err);
+        failed.push(errorMsg);
+        // Continue with other services even if one fails
+      }
+    }
+
+    // Log lazy services that will be initialized on demand
+    if (lazyServices.length > 0) {
+      logger.log(`[ServiceInitialization] ${lazyServices.length} services configured for lazy initialization: ${lazyServices.join(', ')}`);
+    }
+
+    // Log summary
+    if (failed.length === 0) {
+      logger.log(`[ServiceInitialization] All ${initialized.length} critical services initialized successfully`);
+    } else {
+      logger.warn(`[ServiceInitialization] WARNING: ${initialized.length}/${initialized.length + failed.length} services initialized, ${failed.length} failed`);
+      for (const failure of failed) {
+        logger.warn(`[ServiceInitialization]   - ${failure}`);
+      }
+    }
+
+    return { success: failed.length === 0, initialized, failed };
+  } catch (err) {
+    logger.error('[ServiceInitialization] Failed to initialize core services:', err);
+    throw err;
+  }
+}
+
+/**
+ * Dispose all core services
+ * This is called during application shutdown
+ * 
+ * @param container - Service container instance
+ */
+export async function disposeCoreServices(container: ServiceContainer = getServiceContainer()): Promise<void> {
+  logger.log('[ServiceInitialization] Disposing core services...');
+
+  try {
+    // Clear embedding server registration before parallel disposal so the
+    // EmbeddingServer can deregister itself while the StateManager is still alive.
+    // Use tryGet, not getService: on a teardown that follows a partial/failed init
+    // (e.g. STATE_MANAGER itself failed to initialize and _doInit's catch calls shutdown),
+    // getService would CONSTRUCT-and-initialize a fresh StateManager just to dispose it —
+    // a shutdown-resurrection. Only touch an already-live instance.
+    try {
+      const stateManager = container.tryGet<IStateManager>(ServiceNames.STATE_MANAGER);
+      if (stateManager) {
+        await stateManager.clearEmbeddingServer();
+        logger.debug('[ServiceInitialization] Cleared embedding server state before disposal');
+      }
+    } catch {
+      // Non-fatal: embedding server state will be cleaned up on next startup via PID check
+    }
+
+    // Dispose services in reverse dependency order
+    await disposeAllServices(container);
+
+    logger.log('[ServiceInitialization] Core services disposed successfully');
+  } catch (err) {
+    logger.error('[ServiceInitialization] Failed to dispose core services:', err);
+    throw err;
+  }
+}