@lincoln504/pi-research 0.1.12 → 1.0.0

package/src/healthcheck/index.ts

@@ -1,309 +1,315 @@
 /**
  * Health Check Module
  *
- * QUICK connectivity validation for search and scrape tools.
- * Makes real requests to verify network is alive.
- * Fast timeouts, simple checks (just verify tools respond with content).
+ * Validates system capabilities using the central health registry.
+ * This module is stateless and does not cache results.
  */
 
-import { logger } from '../logger.ts';
+import { execFileSync } from 'node:child_process';
 import { getConfig } from '../config.ts';
-import { getManager } from '../infrastructure/searxng-lifecycle.ts';
-import { search } from '../web-research/search.ts';
-import { scrapeSingle } from '../web-research/scrapers.ts';
-import { setSearxngManager } from '../web-research/utils.ts';
-import { getActiveSearxngEngines } from '../utils/searxng-config.ts';
-import { withTimeout } from '../web-research/retry-utils.ts';
-import type { SearXNGResult } from '../web-research/types.ts';
-
-// Health check cache to avoid running multiple health checks concurrently
-interface CachedHealthCheck {
-  result: HealthCheckResult;
-  timestamp: number;
-}
-
-let cachedHealthCheck: CachedHealthCheck | null = null;
-const HEALTH_CHECK_CACHE_TTL_MS = 5 * 60 * 1000; // 5 minutes
-let healthCheckPromise: Promise<HealthCheckResult> | null = null;
-
-// Get timeout from config or use defaults
-const config = getConfig();
-const SEARCH_TIMEOUT_MS = config.HEALTH_CHECK_TIMEOUT_MS || 15000;  // 15s max for search
-const SCRAPE_TIMEOUT_MS = config.HEALTH_CHECK_TIMEOUT_MS ? config.HEALTH_CHECK_TIMEOUT_MS + 5000 : 20000; // 5s longer than search
-
-export interface HealthCheckResult {
-  success: boolean;
-  searchOk: boolean;
-  scrapeOk: boolean;
-  error?: string;
-  details: {
-    searchQuery?: string;
-    searchResultCount?: number;
-    searchDurationMs?: number;
-    workingEngines?: string[];
-    workingEngineCount?: number;
-    scrapedUrl?: string;
-    scrapedContentLength?: number;
-    scrapedDurationMs?: number;
-  };
-}
-
-/**
- * QUICK scrape validation: just check content exists and is readable
- */
-function validateScrapeOutput(markdown: string): { valid: boolean; error?: string } {
-  if (typeof markdown !== 'string') {
-    return { valid: false, error: 'Content not a string' };
-  }
-
-  const trimmed = markdown.trim();
-  if (trimmed.length === 0) {
-    return { valid: false, error: 'Content is empty' };
-  }
-
-  // Just check it has some readable text (not garbage)
-  if (!/[a-zA-Z0-9]{10,}/.test(markdown)) {
-    return { valid: false, error: 'Content not readable' };
-  }
-
-  return { valid: true };
-}
+import { isBrowserAvailable, resolveHeadlessMode } from '../infrastructure/browser/config.ts';
+import { runBrowserHealthCheck } from '../infrastructure/browser/task-execution-service.ts';
+import { getService, tryGetServiceContainerFromCtx, getServiceContainer, ServiceLifecycle } from '../core/service-registry.ts';
+import type { ServiceContainer } from '../core/service-registry.ts';
+import { ServiceNames } from '../core/service-interfaces.ts';
+import type { IStateManager, IHealthRegistryService, IKnowledgeStoreService, ISchedulerService } from '../core/service-interfaces.ts';
+import { healthRegistry as globalHealthRegistry } from './registry.ts';
+import { isNativeStackUnavailableError } from '../knowledge/embedder-utils.ts';
 
 /**
- * Healthcheck uses the same web-research search/scrape helpers as the main tool.
- * Ensure they are wired to the current lifecycle manager instead of relying on
- * an external caller to have registered it beforehand.
+ * Standalone BrowserCapability check, exported so tests can call it directly
+ * without going through the full registry.
  */
-function ensureHealthcheckManager(): void {
-  const manager = getManager();
-  if (!manager) {
-    throw new Error('SearXNG manager not initialized. Call initLifecycle() before runHealthCheck().');
+export async function checkBrowserCapability(): Promise<{ healthy: boolean; error?: string; diagnostic?: Record<string, any> }> {
+  const mockMode = process.env['PI_RESEARCH_MOCK_SEARCH'] === 'true' &&
+                   process.env['PI_RESEARCH_MOCK_SCRAPE'] === 'true';
+  if (isBrowserAvailable() || mockMode) {
+    // resolveHeadlessMode() selects 'virtual' (Xvfb) only under the explicit
+    // PI_RESEARCH_USE_XVFB=true opt-in on a bare Linux TTY. In that case camoufox
+    // spawns Xvfb internally, so fail early (before research starts) if it is not
+    // installed. The default path is headless:true, which needs no Xvfb.
+    if (!mockMode && resolveHeadlessMode() === 'virtual') {
+      try {
+        execFileSync('which', ['Xvfb'], { stdio: 'ignore' });
+      } catch {
+        return {
+          healthy: false,
+          error: 'No display server found on Linux (DISPLAY not set) and Xvfb is not installed. Run: sudo apt install xvfb',
+        };
+      }
+    }
+    return { healthy: true, diagnostic: { status: mockMode ? 'mocked' : 'available' } };
+  } else {
+    return { healthy: false, error: 'Camoufox (browser) not found. Run "npx camoufox-js fetch" to install the browser.' };
   }
-
-  setSearxngManager(manager);
 }
 
 /**
- * Internal health check implementation
- * Runs the actual health check tests
+ * Register all health checks with a registry
  */
-async function performHealthCheck(): Promise<HealthCheckResult> {
-  logger.log('[healthcheck] Starting network connectivity health check...');
+export function registerHealthChecks(registry: IHealthRegistryService, container: ServiceContainer = getServiceContainer()): void {
+  const config = getConfig();
+  const healthTimeoutMs = config.HEALTH_CHECK_TIMEOUT_MS;
 
-  const result: HealthCheckResult = {
-    success: false,
-    searchOk: false,
-    scrapeOk: false,
-    error: undefined,
-    details: {},
-  };
+  // Register Browser Capability Check
+  registry.register('BrowserCapability', checkBrowserCapability, { timeoutMs: healthTimeoutMs, critical: true });
 
-  try {
-    // Skip health check if explicitly requested via env
-    if (process.env['PI_RESEARCH_SKIP_HEALTHCHECK'] === '1') {
-      logger.log('[healthcheck] Skipping health check (PI_RESEARCH_SKIP_HEALTHCHECK=1)');
-      result.success = true;
-      result.searchOk = true;
-      result.scrapeOk = true;
-      return result;
+  // Register Browser Runtime Check
+  registry.register('BrowserRuntime', async (options) => {
+    try {
+      const scheduler = await getService<ISchedulerService>(ServiceNames.SCHEDULER, { container }, container);
+      
+      // Check if initialized but idle (unless forced)
+      if (!scheduler.isReady() && !options?.force) {
+        return { healthy: true, diagnostic: { status: 'ready (idle)' } };
+      }
+      
+      // Perform a real test
+      const searchResult = await runBrowserHealthCheck(undefined, 1, undefined, container);
+      if (searchResult.success) {
+        return { healthy: true, diagnostic: { status: options?.force && !scheduler.isReady() ? 'initialized & active' : 'active' } };
+      } else {
+        return { healthy: false, error: 'Browser healthcheck failed: worker reported failure or page failed to load.' };
+      }
+    } catch (e) {
+      return { healthy: false, error: `Browser healthcheck failed: ${e instanceof Error ? e.message : String(e)}` };
+    }
+    // Honor the configured health timeout but keep a 150s floor: a cold browser
+    // launch (camoufox download/spawn) can legitimately take minutes, so we never
+    // go below that, but a user who raises HEALTH_CHECK_TIMEOUT_MS past it is
+    // respected (same pattern as the KnowledgeStore check's Math.max floor).
+  }, { timeoutMs: Math.max(healthTimeoutMs, 150000), critical: true });
+
+  // Register Knowledge Store Check
+  registry.register('KnowledgeStore', async (options) => {
+    // Idle fast-path — mirrors the BrowserRuntime check above. Read the ALREADY
+    // resolved instance via tryGet(), which does NOT initialize the service;
+    // getService() (below) would run the full LanceDB open + ONNX model load +
+    // WebGPU probe, so a non-forced health check must never take that path on a
+    // cold store. Only inspect for real when the store is already initialized OR an
+    // explicit probe is requested (force).
+    const existing = container.tryGet<IKnowledgeStoreService>(ServiceNames.KNOWLEDGE_STORE);
+    const alreadyInitialized = existing?.lifecycle === ServiceLifecycle.INITIALIZED;
+    if (!alreadyInitialized && !options?.force) {
+      const idleCwd = existing?.getCwd() ?? process.cwd();
+      if (getConfig(idleCwd).KNOWLEDGE_STORE_MODE === 'none') {
+        return { healthy: true, diagnostic: { status: 'disabled in config' } };
+      }
+      // A store that resolved-then-disabled reports WHY, accurately: 'native' is a
+      // permanent platform capability gap; 'mode' is a revivable Knowledge-Mode=none
+      // (which may have since been re-enabled — it re-initializes on next real use).
+      // Never claim "native unavailable" for a mode-disable on a perfectly capable host.
+      if (existing?.lifecycle === ServiceLifecycle.DISABLED) {
+        const reason = existing.getDisabledReason();
+        return { healthy: true, diagnostic: {
+          status: reason === 'native'
+            ? 'disabled (native embedding/vector stack unavailable on this platform)'
+            : 'disabled',
+        } };
+      }
+      // A DISPOSED/DISPOSING service is not "ready" — report it accurately without
+      // initializing anything (it re-resolves lazily on next real use, so still healthy).
+      const status = existing?.lifecycle === ServiceLifecycle.INITIALIZING
+        ? 'initializing'
+        : (existing?.lifecycle === ServiceLifecycle.DISPOSED || existing?.lifecycle === ServiceLifecycle.DISPOSING)
+          ? 'disposed (not running)'
+          : 'ready (idle)';
+      return { healthy: true, diagnostic: { status } };
     }
 
-    ensureHealthcheckManager();
-
-    // PHASE 1: Test general web search engines (Bing, DuckDuckGo, Brave — NOT Wikipedia)
-    logger.log('[healthcheck] Phase 1: Testing general web search engines (timeout: ' + SEARCH_TIMEOUT_MS + 'ms)...');
-    const searchQuery = 'open source software';
-    const searchStartTime = Date.now();
-
-    let queryResults;
+    // Full inspection (already-initialized OR forced): resolve via getService —
+    // cheap when warm (early-returns), full init only on a forced cold probe.
+    // Resolve cwd from the live service (it captured ctx.cwd at init) so the
+    // health check reads the SAME config the store actually uses. Reading
+    // process.cwd() here silently ignored SDK/CLI cwd overrides.
+    let service: IKnowledgeStoreService | null = null;
+    let initError: unknown = null;
     try {
-      queryResults = await withTimeout(
-        search([searchQuery]),
-        SEARCH_TIMEOUT_MS,
-        'Search'
-      );
-    } catch (err) {
-      const msg = err instanceof Error ? err.message : String(err);
-      result.error = `Search request failed: ${msg}. Network may be unreachable or SearXNG not responding.`;
-      logger.error('[healthcheck] Search error:', result.error);
-      return result;
+      service = await getService<IKnowledgeStoreService>(ServiceNames.KNOWLEDGE_STORE, { container }, container);
+    } catch (e) {
+      // service stays null; classify the failure below (native-unavailable vs real).
+      initError = e;
     }
-
-    const searchDurationMs = Date.now() - searchStartTime;
-
-    if (queryResults.length === 0 || !queryResults[0]) {
-      result.error = 'Search returned empty result object (SearXNG not initialized?)';
-      logger.error('[healthcheck]', result.error);
-      return result;
+    const cwd = service?.getCwd() ?? process.cwd();
+    const config = getConfig(cwd);
+    if (config.KNOWLEDGE_STORE_MODE === 'none') {
+      return { healthy: true, diagnostic: { status: 'disabled in config' } };
     }
-
-    const qr = queryResults[0];
-    if (qr.error) {
-      const errMsg = qr.error.message || String(qr.error);
-      result.error = `Search request failed: ${errMsg}. SearXNG or engines are not responding.`;
-      logger.error('[healthcheck]', result.error);
-      return result;
+    // The native ML/vector stack ships no prebuilt for some platforms (Intel macOS
+    // / darwin-x64 has no onnxruntime-node binary nor @lancedb native binding). That
+    // is a permanent capability gap, not a fault — report the store as DISABLED
+    // (healthy) so research still runs without the optional cache. Otherwise this
+    // critical component drags overall health to 'unhealthy' and quick (depth-0)
+    // research aborts with "Research cannot start" for any fresh user on such a host.
+    if (isNativeStackUnavailableError(initError)) {
+      return { healthy: true, diagnostic: { status: 'disabled (native embedding/vector stack unavailable on this platform)' } };
     }
-
-    // Check for at least 2 working general search engines (not Wikipedia)
-    // Wikipedia is an encyclopedic engine, not suitable for general web research
-    // Load the list of active engines from the actual SearXNG config (not hardcoded)
-    const generalEngines = getActiveSearxngEngines();
-    if (generalEngines.length === 0) {
-      result.error = 'No active general search engines found in SearXNG configuration';
-      logger.error('[healthcheck]', result.error);
-      return result;
+    // getService can SUCCEED on a native-unavailable platform: the service memoizes
+    // the failure as DISABLED instead of throwing, so initError stays null and the
+    // getStore()/getEmbedder() null checks below would report a false UNHEALTHY
+    // ("Embedder service not available") on a forced check — contradicting the
+    // non-forced path's correct "disabled" verdict above. Report the same verdict.
+    if (service?.lifecycle === ServiceLifecycle.DISABLED) {
+      const reason = service.getDisabledReason();
+      return { healthy: true, diagnostic: {
+        status: reason === 'native'
+          ? 'disabled (native embedding/vector stack unavailable on this platform)'
+          : 'disabled',
+      } };
     }
-    logger.log(`[healthcheck] Checking for results from engines: [${generalEngines.join(', ')}]`);
-
-    const generalResults = qr.results.filter((r: SearXNGResult) =>
-      generalEngines.includes((r.engine || '').toLowerCase())
-    );
-
-    // Count how many engines returned at least one result
-    const engineCounts = new Map<string, number>();
-    generalEngines.forEach(e => engineCounts.set(e, 0));
-    generalResults.forEach((r: SearXNGResult) => {
-      const engine = (r.engine || '').toLowerCase();
-      if (engineCounts.has(engine)) {
-        engineCounts.set(engine, (engineCounts.get(engine) || 0) + 1);
+    try {
+      if (!service) {
+        return { healthy: false, error: 'Knowledge store service not available' };
       }
-    });
-
-    const workingEngines = Array.from(engineCounts.entries()).filter(([_, count]) => count > 0);
-    const workingEngineCount = workingEngines.length;
+      const store = await service.getStore();
+      const counts = store ? await store.countScoped() : { local: 0, global: 0, projects: 0 };
+      const embedder = await service.getEmbedder();
 
-    // Require at least 1 engine to return results (local use may have rate limits)
-    if (workingEngineCount < 1) {
-      const engineReport = Array.from(engineCounts.entries())
-        .map(([e, c]) => `${e}: ${c}`)
-        .join(', ');
-      result.error = `No working engines found: 0/${generalEngines.length} returned results. Need at least 1 engine. Engine results: ${engineReport}. Your network or search engines may be blocked.`;
-      logger.error('[healthcheck] Search validation failed:', result.error);
-      return result;
-    }
-
-    result.searchOk = true;
-    result.details.searchQuery = searchQuery;
-    result.details.searchResultCount = generalResults.length;
-    result.details.searchDurationMs = searchDurationMs;
-    result.details.workingEngines = workingEngines.map(([e, _]) => e);
-    result.details.workingEngineCount = workingEngineCount;
-    const workingEnginesList = workingEngines.map(([e, _]) => e).join(', ');
-    logger.log(`[healthcheck] ✓ Search OK: ${generalResults.length} results from ${workingEngineCount} engines [${workingEnginesList}] in ${searchDurationMs}ms`);
-
-    // PHASE 2: Test scrape with timeout enforcement
-    logger.log('[healthcheck] Phase 2: Testing scrape tool (timeout: ' + SCRAPE_TIMEOUT_MS + 'ms)...');
-    const scrapeUrl = 'https://en.wikipedia.org/wiki/Python_(programming_language)';
-    const scrapeStartTime = Date.now();
+      if (!embedder) {
+        return { healthy: false, error: 'Embedder service not available' };
+      }
 
-    let scrapeResult;
-    try {
-      scrapeResult = await withTimeout(
-        scrapeSingle(scrapeUrl),
-        SCRAPE_TIMEOUT_MS,
-        'Scrape'
-      );
-    } catch (err) {
-      const msg = err instanceof Error ? err.message : String(err);
-      result.error = `Scrape request failed: ${msg}. Network timeout or target unreachable.`;
-      logger.error('[healthcheck]', result.error);
-      return result;
-    }
+      // A remote embedding-server client reports isInitialized()===true
+      // unconditionally (the server, not the client, owns the model), so trusting
+      // it would mask a dead server. When the embedder exposes a liveness probe
+      // (fetchHealth on the HTTP client), ping it so a down server is reported
+      // unhealthy instead of a false "ready". This does NOT warm a local GPU model.
+      const probe = (embedder as { fetchHealth?: () => Promise<void> }).fetchHealth;
+      if (typeof probe === 'function') {
+        try {
+          await probe.call(embedder);
+        } catch (e) {
+          return { healthy: false, error: `Embedding server unreachable: ${e instanceof Error ? e.message : String(e)}` };
+        }
+      }
 
-    const scrapeDurationMs = Date.now() - scrapeStartTime;
+      // Lazy-aware health check: if not initialized, we check if the store is open
+      // but don't force a model load to GPU just for the health check (unless forced).
+      if (!embedder.isInitialized() && !options?.force) {
+          return {
+              healthy: true,
+              diagnostic: {
+                  status: 'ready (idle)',
+                  device: embedder.getOriginalDevice(),
+                  localEntries: counts.local,
+                  globalEntries: counts.global
+              }
+          };
+      }
 
-    if (!scrapeResult) {
-      result.error = 'Scrape returned null result (scraper crashed?)';
-      logger.error('[healthcheck]', result.error);
-      return result;
-    }
+      // Force initialization if requested
+      if (options?.force && !embedder.isInitialized()) {
+          await embedder.embed(' ');
+      }
 
-    if (scrapeResult.source === 'failed') {
-      result.error = `Scrape failed: ${scrapeResult.error || 'unknown error'}. Check if target URL is accessible.`;
-      logger.error('[healthcheck]', result.error);
-      return result;
+      const device = embedder.getDevice();
+      return { 
+          healthy: true, 
+          diagnostic: { 
+              status: 'initialized',
+              device,
+              model: config.EMBEDDING_MODEL,
+              localEntries: counts.local,
+              globalEntries: counts.global,
+              totalProjects: counts.projects
+          } 
+      };
+    } catch (e) {
+      // Same platform-capability gap as above, but surfacing only when the store
+      // is touched lazily (getStore/getEmbedder load the native binding here).
+      if (isNativeStackUnavailableError(e)) {
+        return { healthy: true, diagnostic: { status: 'disabled (native embedding/vector stack unavailable on this platform)' } };
+      }
+      return { healthy: false, error: `Knowledge store healthcheck failed: ${e instanceof Error ? e.message : String(e)}` };
     }
+  }, { timeoutMs: Math.max(healthTimeoutMs, 45000) });
 
-    // ROBUST validation of scraped content
-    const markdown = scrapeResult.markdown || '';
-    const scrapeValidation = validateScrapeOutput(markdown);
-    if (!scrapeValidation.valid) {
-      result.error = `Scrape validation failed: ${scrapeValidation.error}`;
-      logger.error('[healthcheck]', result.error);
-      return result;
+  // Register State Manager Check
+  registry.register('StateManager', async () => {
+    try {
+      const stateManager = await getService<IStateManager>(ServiceNames.STATE_MANAGER, { container }, container);
+      const stats = await stateManager.getMetrics();
+      const gpuOwner = await stateManager.getGpuOwner();
+      
+      return { 
+          healthy: true, 
+          diagnostic: { 
+              status: 'operational',
+              sessions: stats.activeSessions,
+              gpuLocked: !!gpuOwner,
+              gpuOwner: gpuOwner?.sessionId || 'none'
+          } 
+      };
+    } catch (e) {
+      return { healthy: false, error: `State manager healthcheck failed: ${e instanceof Error ? e.message : String(e)}` };
     }
+  }, { timeoutMs: healthTimeoutMs });
+}
 
-    result.scrapeOk = true;
-    result.details.scrapedUrl = scrapeUrl;
-    result.details.scrapedContentLength = markdown.length;
-    result.details.scrapedDurationMs = scrapeDurationMs;
-    logger.log(`[healthcheck] ✓ Scrape OK: ${markdown.length} bytes in ${scrapeDurationMs}ms`);
+// Ensure global registry is populated
+registerHealthChecks(globalHealthRegistry);
 
-    // All checks passed
-    result.success = true;
-    const totalMs = searchDurationMs + scrapeDurationMs;
-    logger.log(`[healthcheck] ✓ HEALTH CHECK PASSED in ${totalMs}ms - all systems ready`);
-    return result;
-  } catch (err) {
-    result.error = `Unexpected error during health check: ${err instanceof Error ? err.message : String(err)}`;
-    logger.error('[healthcheck] Unexpected error:', err);
-    return result;
-  }
+/**
+ * Decide whether a FAILED health check is a transient "pool busy" condition (research
+ * should proceed) rather than a genuine failure (research must abort).
+ *
+ * Returns true when the browser is installed/constructible — BrowserCapability is healthy
+ * (it never touches the worker pool) — AND every unhealthy component failed with a TIMEOUT,
+ * i.e. its probe queued out behind in-flight scrapes on the shared fixed-size worker pool
+ * under load. Under sustained concurrency the runtime probe and the StateManager/KnowledgeStore
+ * probes (which share the same congested pool/GPU) frequently time out together, so any
+ * combination of timed-out probes is treated as "busy", not "dead". The pool is operational
+ * and the per-task search/scrape timeouts already bound the real work, so aborting the whole
+ * session on this signal needlessly discards a research category. A non-timeout failure
+ * (browser not installed, "connection refused", embedder missing) returns false → caller
+ * must abort.
+ */
+export function isBusyPoolHealthFailure(
+  health: { components?: Array<{ component?: string; healthy?: boolean; error?: string }> },
+): boolean {
+  const components = health.components || [];
+  const capability = components.find(c => c.component === 'BrowserCapability');
+  // BrowserCapability is the liveness signal: it only checks the browser is installed
+  // and constructible, never touching the worker pool. If it is healthy (or absent),
+  // the browser CAN run — so any failures elsewhere are about throughput, not death.
+  const capabilityOk = !capability || capability.healthy !== false;
+  const unhealthy = components.filter(c => c.healthy === false);
+  // Proceed only when EVERY unhealthy component failed with a TIMEOUT. Under sustained
+  // concurrent load the BrowserRuntime probe — and often the StateManager/KnowledgeStore
+  // probes sharing the same congested pool/GPU — all queue out together; requiring the
+  // runtime probe to be the SOLE failure was too strict and let a second co-timed-out
+  // probe abort an otherwise-operational session. A non-timeout error (browser not
+  // installed, "connection refused", embedder missing) is a real fault → returns false.
+  const isTimeout = (c: { error?: string }) => /tim(e|ed)\s*out|timeout/i.test(String(c.error || ''));
+  return capabilityOk && unhealthy.length > 0 && unhealthy.every(isTimeout);
 }
 
 /**
- * Run health check with caching to avoid concurrent executions
- * If a health check is already in progress, returns the same promise
- * If a recent successful health check is cached, returns the cached result
+ * Perform a full system health check
  */
-export async function runHealthCheck(): Promise<HealthCheckResult> {
-  const now = Date.now();
-
-  // Check if we have a recent cached result
-  if (cachedHealthCheck) {
-    const age = now - cachedHealthCheck.timestamp;
-    if (age < HEALTH_CHECK_CACHE_TTL_MS) {
-      logger.log(`[healthcheck] Using cached health check result (${Math.round(age / 1000)}s old)`);
-      return cachedHealthCheck.result;
-    } else {
-      logger.log(`[healthcheck] Cached health check result expired (${Math.round(age / 1000)}s old)`);
-      cachedHealthCheck = null;
-    }
-  }
-
-  // If a health check is already running, return the existing promise
-  if (healthCheckPromise) {
-    logger.log('[healthcheck] Health check already in progress, reusing existing promise');
-    return healthCheckPromise;
+export async function runHealthCheck(options?: { force?: boolean; ctx?: any }) {
+  const container = tryGetServiceContainerFromCtx(options?.ctx);
+  
+  let registry: IHealthRegistryService;
+  try {
+    registry = await getService<IHealthRegistryService>(ServiceNames.HEALTH_REGISTRY, options?.ctx, container);
+  } catch {
+    // Fallback to global registry if service not found (CLI/Legacy)
+    registry = globalHealthRegistry;
   }
 
-  // Start a new health check
-  healthCheckPromise = (async () => {
-    try {
-      const result = await performHealthCheck();
-      // Cache successful results
-      if (result.success) {
-        cachedHealthCheck = {
-          result,
-          timestamp: now,
-        };
-      }
-      return result;
-    } finally {
-      // Clear the promise so a new health check can be started
-      healthCheckPromise = null;
-    }
-  })();
-
-  return healthCheckPromise;
+  const result = await registry.runAll(options);
+  return {
+    success: result.status !== 'unhealthy',
+    status: result.status,
+    components: result.components,
+    error: result.status === 'unhealthy' 
+      ? result.components.find(c => !c.healthy && registry.isCritical(c.component))?.error
+      : undefined
+  };
 }
 
 /**
- * Clear the health check cache
- * Useful for testing or forcing a recheck
+ * Export health registry for external use
  */
-export function clearHealthCheckCache(): void {
-  cachedHealthCheck = null;
-  logger.log('[healthcheck] Health check cache cleared');
-}
+export { globalHealthRegistry as healthRegistry };