claude-brain 0.30.2 → 0.30.3

package/src/cli/commands/serve.ts

@@ -1,463 +1,466 @@
-import { loadConfig } from '@/config'
-import { createLogger, createComponentLogger } from '@/utils'
-import { GlobalErrorHandler, CleanupManager } from '@/utils'
-import { ClaudeBrainMCPServer } from '@/server'
-import { initializeServices, shutdownServices, getVaultService, getMemoryService } from '@/server/services'
-import { createOrchestrator, type Orchestrator } from '@/orchestrator'
-import { ensureHomeDirectory } from '@/cli/auto-setup'
-import { ServerPidManager } from '@/server/pid-manager'
-
-const BANNER = `
-╔═══════════════════════════════════════════════════════╗
-║                    CLAUDE BRAIN                        ║
-║     Local Development Assistant with Memory           ║
-╚═══════════════════════════════════════════════════════╝
-`
-
-export async function runServe() {
-  // Auto-initialize home directory on first run
-  ensureHomeDirectory()
-
-  const httpOnly = process.argv.includes('--http-only')
-  const pidManager = new ServerPidManager()
-  const existingInstance = pidManager.getRunningInstance()
-
-  // ── Decision tree ──────────────────────────────────────────
-  // httpOnly + existing daemon → exit (duplicate daemon)
-  // httpOnly + no daemon      → start as daemon (full services + HTTP + idle watchdog)
-  // !httpOnly + healthy daemon → run as proxy (thin MCP bridge, no services)
-  // !httpOnly + no daemon      → start as daemon + MCP stdio (become daemon)
-
-  if (httpOnly && existingInstance) {
-    console.error(`[claude-brain] Primary instance already running (PID ${existingInstance.pid}). Exiting.`)
-    process.exit(0)
-  }
-
-  if (!httpOnly && existingInstance) {
-    // Check if existing daemon is healthy before committing to proxy mode
-    const healthy = await isDaemonHealthy(existingInstance.port)
-    if (healthy) {
-      return runAsProxy(existingInstance.port)
-    }
-    // Daemon not healthy — clean up stale PID and start as daemon
-    pidManager.cleanup()
-  }
-
-  // ── Start as daemon ────────────────────────────────────────
-  return runAsDaemon(httpOnly, pidManager)
-}
-
-/** Check if the daemon at the given port is responsive, initialized, and can serve MCP tools */
-async function isDaemonHealthy(port: number): Promise<boolean> {
-  try {
-    const healthRes = await fetch(`http://localhost:${port}/api/health`, {
-      signal: AbortSignal.timeout(2000),
-    })
-    const healthJson = await healthRes.json() as any
-    if (healthJson.success !== true || healthJson.initialized !== true) return false
-
-    // Verify MCP proxy endpoints actually work (old versions return 404)
-    const toolsRes = await fetch(`http://localhost:${port}/api/mcp/list-tools`, {
-      signal: AbortSignal.timeout(2000),
-    })
-    const toolsJson = await toolsRes.json() as any
-    return toolsJson.success === true && Array.isArray(toolsJson.data?.tools)
-  } catch {
-    return false
-  }
-}
-
-/** Run as thin MCP proxy — forward all MCP calls to daemon via HTTP */
-async function runAsProxy(daemonPort: number) {
-  const config = await loadConfig()
-  const logger = createLogger(config.logLevel, config.logFilePath)
-  const mainLogger = createComponentLogger(logger, 'proxy')
-
-  mainLogger.info({ daemonPort }, 'Starting as MCP proxy → daemon')
-
-  const { McpProxyServer } = await import('@/server/mcp-proxy')
-
-  let isStopping = false
-  const proxy = new McpProxyServer({
-    daemonUrl: `http://localhost:${daemonPort}`,
-    serverName: config.serverName,
-    serverVersion: config.serverVersion,
-    onStdinClose: () => {
-      if (isStopping) return
-      isStopping = true
-      mainLogger.info('stdin closed — proxy exiting')
-      proxy.stop().finally(() => process.exit(0))
-    },
-  })
-
-  const stopProxy = async (signal: string) => {
-    if (isStopping) return
-    isStopping = true
-    mainLogger.info({ signal }, 'Proxy shutting down')
-    await proxy.stop()
-    process.exit(0)
-  }
-
-  process.on('SIGTERM', () => stopProxy('SIGTERM'))
-  process.on('SIGINT', () => stopProxy('SIGINT'))
-  if (process.platform !== 'win32') {
-    process.on('SIGHUP', () => stopProxy('SIGHUP'))
-  }
-
-  await proxy.start()
-  mainLogger.info('MCP proxy ready — forwarding to daemon')
-}
-
-/** Run as full daemon with services, HTTP, and optionally MCP stdio */
-async function runAsDaemon(httpOnly: boolean, pidManager: ServerPidManager) {
-  // Auto-install Claude Code hooks (idempotent, non-fatal)
-  try {
-    const { installHooks } = await import('@/hooks/installer')
-    const hookResult = installHooks()
-    if (hookResult.message !== 'Hooks already installed') {
-      console.error(`[claude-brain] ${hookResult.message}`)
-    }
-  } catch (error) {
-    console.error(`[claude-brain] Hook auto-install skipped: ${error instanceof Error ? error.message : 'unknown error'}`)
-  }
-
-  // Auto-install shell auto-start if not already present
-  try {
-    const { isAutoStartInstalled, installAutoStart } = await import('@/cli/auto-start')
-    if (!isAutoStartInstalled()) {
-      const result = installAutoStart()
-      if (result.success && result.profilePath) {
-        console.error(`[claude-brain] Auto-start installed in ${result.profilePath}`)
-      }
-    }
-  } catch (error) {
-    // Non-fatal — auto-start is a convenience feature
-  }
-
-  // Auto-install CLAUDE.md if not present
-  try {
-    const { existsSync, readFileSync, writeFileSync, mkdirSync } = await import('node:fs')
-    const { join, resolve, dirname } = await import('node:path')
-    const { homedir } = await import('node:os')
-    const { fileURLToPath } = await import('node:url')
-    const claudeMdDest = join(homedir(), '.claude', 'CLAUDE.md')
-    const pkgRoot = resolve(dirname(fileURLToPath(import.meta.url)), '..', '..', '..')
-    const claudeMdSrc = join(pkgRoot, 'assets', 'CLAUDE.md')
-    if (existsSync(claudeMdSrc) && !existsSync(claudeMdDest)) {
-      mkdirSync(join(homedir(), '.claude'), { recursive: true })
-      writeFileSync(claudeMdDest, readFileSync(claudeMdSrc, 'utf-8'), 'utf-8')
-      console.error('[claude-brain] CLAUDE.md installed to ~/.claude/CLAUDE.md')
-    }
-  } catch {
-    // Non-fatal
-  }
-
-  const config = await loadConfig()
-
-  if (config.logLevel === 'debug' || config.logLevel === 'info') {
-    console.error(BANNER)
-  }
-
-  const logger = createLogger(config.logLevel, config.logFilePath)
-  const mainLogger = createComponentLogger(logger, 'main')
-
-  new GlobalErrorHandler(logger)
-  const cleanup = new CleanupManager(logger)
-
-  mainLogger.info({
-    serverName: config.serverName,
-    serverVersion: config.serverVersion,
-    vaultPath: config.vaultPath,
-    nodeEnv: config.nodeEnv
-  }, 'Claude Brain starting...')
-
-  mainLogger.info({
-    logLevel: config.logLevel,
-    enableFileWatch: config.enableFileWatch,
-    cacheSize: config.cacheSize
-  }, 'Configuration loaded')
-
-  // Only start ChromaDB if explicitly enabled in config
-  let chromaReady = false
-  if (config.chromadb?.enabled) {
-    mainLogger.info('ChromaDB enabled, ensuring it is available...')
-    const { ensureChromaRunning } = await import('@/cli/commands/chroma')
-    chromaReady = await ensureChromaRunning({ silent: process.env.NODE_ENV === 'production' })
-    mainLogger.info({ chromaReady }, chromaReady ? 'ChromaDB is ready' : 'ChromaDB not available, using SQLite fallback')
-  } else {
-    mainLogger.info('Using SQLite FTS5 storage (ChromaDB disabled)')
-  }
-
-  mainLogger.info('Initializing services...')
-  await initializeServices(config, logger)
-  mainLogger.info('Services initialized successfully')
-
-  // Initialize orchestrator for event-driven features
-  let orchestrator: Orchestrator | null = null
-  try {
-    const vault = getVaultService()
-    const memory = getMemoryService()
-
-    orchestrator = createOrchestrator(logger, vault, memory, {
-      maxConcurrentOperations: 5,
-      debounceMs: 5000
-    })
-
-    await orchestrator.initialize()
-    mainLogger.info('Orchestrator initialized successfully')
-  } catch (error) {
-    mainLogger.warn({ error }, 'Failed to initialize orchestrator, continuing without event-driven features')
-  }
-
-  const mcpServer = new ClaudeBrainMCPServer(config, logger, {
-    events: {
-      onConnectionStateChange: (state) => {
-        mainLogger.info({ state }, 'MCP connection state changed')
-      },
-      onError: (error) => {
-        mainLogger.error({ error: error.message }, 'MCP server error')
-      },
-      onRequest: (toolName, requestId) => {
-        pidManager.touchActivity()
-        mainLogger.debug({ toolName, requestId }, 'Tool request received')
-      },
-      onResponse: (toolName, requestId, durationMs) => {
-        mainLogger.debug({ toolName, requestId, durationMs }, 'Tool response sent')
-      }
-    }
-  })
-
-  cleanup.register(async () => {
-    await mcpServer.stop()
-  })
-
-  // Register orchestrator cleanup before services shutdown
-  if (orchestrator) {
-    cleanup.register(async () => {
-      orchestrator!.shutdown()
-      mainLogger.info('Orchestrator shut down')
-    })
-  }
-
-  cleanup.register(async () => {
-    await shutdownServices()
-  })
-
-  // ── Idempotent shutdown guard ────────────────────────────
-  let isShuttingDown = false
-  const shutdown = async (signal: string) => {
-    if (isShuttingDown) return
-    isShuttingDown = true
-    mainLogger.info({ signal }, 'Shutting down...')
-    await cleanup.cleanup()
-    process.exit(0)
-  }
-
-  // ── Primary daemon: HTTP server + background services ────
-  // Write PID file and register cleanup
-  pidManager.writePidFile(config.port)
-  pidManager.registerCleanupHandlers()
-
-  cleanup.register(async () => {
-    pidManager.cleanup()
-  })
-
-  // Start HTTP API server
-  const { HttpApiServer } = await import('@/server/http-api')
-  const httpServer = new HttpApiServer(config, logger)
-
-  // Wire activity tracker to PID manager for idle watchdog
-  httpServer.setActivityTracker(() => pidManager.touchActivity())
-
-  cleanup.register(async () => {
-    await httpServer.stop()
-  })
-
-  // Phase 21: Use session tracker from services
-  {
-    const { getSessionTracker } = await import('@/server/services')
-    const sessionTracker = getSessionTracker()
-    if (sessionTracker) {
-      httpServer.setSessionTracker(sessionTracker)
-      mainLogger.info('Session tracker wired to HTTP server')
-    }
-  }
-
-  // Phase 28: Wire code intelligence to HTTP server
-  {
-    const { getCodeIndexer, getCodeQuery } = await import('@/server/services')
-    const codeIndexer = getCodeIndexer()
-    const codeQuery = getCodeQuery()
-    if (codeIndexer && codeQuery) {
-      httpServer.setCodeIntelligence(codeIndexer, codeQuery)
-      mainLogger.info('Code intelligence wired to HTTP server')
-    }
-  }
-
-  // Phase 29: Wire code linker to HTTP server
-  {
-    const { getCodeLinker } = await import('@/server/services')
-    const codeLinker = getCodeLinker()
-    if (codeLinker) {
-      httpServer.setCodeLinker(codeLinker)
-      mainLogger.info('Code linker wired to HTTP server')
-    }
-  }
-
-  // Phase 30: Activity log pruning on startup + periodic cleanup
-  {
-    const memory = getMemoryService()
-    if (memory?.isInitialized()) {
-      try {
-        const { startPeriodicPruning } = await import('@/memory/pruning')
-        const db = memory.database.getDb()
-        const stopPruning = startPeriodicPruning(db, logger, 30)
-        cleanup.register(async () => {
-          stopPruning()
-          mainLogger.info('Activity log pruning stopped')
-        })
-        mainLogger.info('Activity log pruning initialized')
-      } catch (error) {
-        mainLogger.warn({ error }, 'Failed to initialize activity log pruning')
-      }
-    }
-  }
-
-  // Phase 30: Optional LLM compression
-  if (config.compression?.enabled) {
-    try {
-      const { ObservationCompressor } = await import('@/memory/compression')
-      const { getBrainRouter } = await import('@/routing/router')
-      const compressor = new ObservationCompressor(config.compression, logger)
-      const router = getBrainRouter(logger)
-      router.setCompressor(compressor)
-      mainLogger.info({ provider: config.compression.provider, model: config.compression.model }, 'LLM compression enabled')
-    } catch (error) {
-      mainLogger.warn({ error }, 'Failed to initialize LLM compression')
-    }
-  }
-
-  // Phase 31: Auto-update checker
-  let autoUpdater: InstanceType<typeof import('@/server/auto-updater').AutoUpdater> | null = null
-  if (config.autoUpdate?.enabled !== false) {
-    try {
-      const { AutoUpdater } = await import('@/server/auto-updater')
-      autoUpdater = new AutoUpdater(
-        {
-          enabled: config.autoUpdate?.enabled ?? true,
-          checkIntervalHours: config.autoUpdate?.checkIntervalHours ?? 24,
-          autoRestart: config.autoUpdate?.autoRestart ?? true,
-        },
-        mainLogger
-      )
-
-      // Check for updates on startup (non-blocking)
-      autoUpdater.check().then(result => {
-        if (result.updateAvailable && result.latestVersion) {
-          mainLogger.info(
-            { current: result.currentVersion, latest: result.latestVersion },
-            'Update available! Run: claude-brain update'
-          )
-        }
-      }).catch(() => {})
-
-      // Schedule periodic checks
-      autoUpdater.schedulePeriodicCheck()
-
-      cleanup.register(async () => {
-        autoUpdater?.stopPeriodicCheck()
-        mainLogger.info('Auto-updater stopped')
-      })
-
-      mainLogger.info('Auto-updater initialized')
-    } catch (error) {
-      mainLogger.warn({ error }, 'Failed to initialize auto-updater')
-    }
-  }
-
-  // Start HTTP server after MCP server is ready
-  setTimeout(async () => {
-    try {
-      await httpServer.start()
-      mainLogger.info({ port: config.port }, 'HTTP API server started')
-
-      // Drain hook queue after HTTP server is ready
-      try {
-        const { drainQueue } = await import('@/hooks/queue')
-        const drained = await drainQueue(config.port)
-        if (drained > 0) {
-          mainLogger.info({ drained }, 'Drained hook queue')
-        }
-      } catch (error) {
-        mainLogger.debug({ error }, 'No hook queue to drain')
-      }
-    } catch (error: any) {
-      // EADDRINUSE: kill the stale process and retry once
-      if (error?.code === 'EADDRINUSE' || String(error).includes('EADDRINUSE')) {
-        mainLogger.warn({ port: config.port }, 'Port in use — killing stale process and retrying')
-        try {
-          const { killProcessOnPort } = await import('@/utils/kill-port')
-          const killed = killProcessOnPort(config.port)
-          if (killed.length > 0) {
-            mainLogger.info({ killed }, 'Killed stale process(es) on port')
-          }
-          await new Promise(r => setTimeout(r, 1000))
-          await httpServer.start()
-          mainLogger.info({ port: config.port }, 'HTTP API server started (after recovery)')
-
-          // Drain hook queue on retry success too
-          try {
-            const { drainQueue } = await import('@/hooks/queue')
-            const drained = await drainQueue(config.port)
-            if (drained > 0) {
-              mainLogger.info({ drained }, 'Drained hook queue')
-            }
-          } catch {}
-        } catch (retryError) {
-          mainLogger.error({ error: retryError }, 'Failed to start HTTP API server after recovery — MCP stdio still works')
-        }
-      } else {
-        mainLogger.error({ error }, 'Failed to start HTTP API server')
-      }
-    }
-  }, 2000)
-
-  // ── Signal handlers ──────────────────────────────────────
-  process.on('SIGTERM', () => shutdown('SIGTERM'))
-  process.on('SIGINT', () => shutdown('SIGINT'))
-  if (process.platform !== 'win32') {
-    process.on('SIGHUP', () => shutdown('SIGHUP'))
-  }
-
-  if (httpOnly) {
-    // HTTP-only daemon mode: no MCP stdio. Use idle watchdog instead of infinite keepAlive.
-    mainLogger.info('HTTP-only mode — MCP stdio disabled (background daemon)')
-
-    const idleTimeoutMs = (config.daemon?.idleTimeoutMinutes ?? 30) * 60 * 1000
-    if (idleTimeoutMs > 0) {
-      const watchdog = setInterval(() => {
-        const idleMs = pidManager.getIdleMs()
-        if (idleMs >= idleTimeoutMs) {
-          mainLogger.info({ idleMs, idleTimeoutMs }, 'Idle timeout reached — shutting down daemon')
-          clearInterval(watchdog)
-          shutdown('idle-timeout')
-        }
-      }, 60_000)
-      cleanup.register(async () => clearInterval(watchdog))
-      mainLogger.info({ idleTimeoutMinutes: config.daemon?.idleTimeoutMinutes ?? 30 }, 'Idle watchdog started')
-    } else {
-      // idleTimeoutMinutes=0 means never self-terminate (old behavior)
-      const keepAlive = setInterval(() => {}, 60_000 * 60)
-      cleanup.register(async () => clearInterval(keepAlive))
-      mainLogger.info('Idle watchdog disabled (idleTimeoutMinutes=0)')
-    }
-  } else {
-    // MCP stdio mode: start MCP server and detect stdin closure
-    await mcpServer.start()
-    mainLogger.info('Claude Brain MCP server ready and listening for connections')
-
-    // Detect stdin close — Claude Code disconnected
-    process.stdin.on('end', () => shutdown('stdin-end'))
-    process.stdin.on('close', () => shutdown('stdin-close'))
-  }
-}
+import { loadConfig } from '@/config'
+import { createLogger, createComponentLogger } from '@/utils'
+import { GlobalErrorHandler, CleanupManager } from '@/utils'
+import { ClaudeBrainMCPServer } from '@/server'
+import { initializeServices, shutdownServices, getVaultService, getMemoryService } from '@/server/services'
+import { createOrchestrator, type Orchestrator } from '@/orchestrator'
+import { ensureHomeDirectory } from '@/cli/auto-setup'
+import { ServerPidManager } from '@/server/pid-manager'
+
+const BANNER = `
+╔═══════════════════════════════════════════════════════╗
+║                    CLAUDE BRAIN                        ║
+║     Local Development Assistant with Memory           ║
+╚═══════════════════════════════════════════════════════╝
+`
+
+export async function runServe() {
+  // Auto-initialize home directory on first run
+  ensureHomeDirectory()
+
+  const httpOnly = process.argv.includes('--http-only')
+  const pidManager = new ServerPidManager()
+  const existingInstance = pidManager.getRunningInstance()
+
+  // ── Decision tree ──────────────────────────────────────────
+  // httpOnly + existing daemon → exit (duplicate daemon)
+  // httpOnly + no daemon      → start as daemon (full services + HTTP + idle watchdog)
+  // !httpOnly + healthy daemon → run as proxy (thin MCP bridge, no services)
+  // !httpOnly + no daemon      → start as daemon + MCP stdio (become daemon)
+
+  if (httpOnly && existingInstance) {
+    console.error(`[claude-brain] Primary instance already running (PID ${existingInstance.pid}). Exiting.`)
+    process.exit(0)
+  }
+
+  if (!httpOnly && existingInstance) {
+    // Check if existing daemon is healthy before committing to proxy mode
+    const healthy = await isDaemonHealthy(existingInstance.port)
+    if (healthy) {
+      return runAsProxy(existingInstance.port)
+    }
+    // Daemon not healthy — clean up stale PID and start as daemon
+    pidManager.cleanup()
+  }
+
+  // ── Start as daemon ────────────────────────────────────────
+  return runAsDaemon(httpOnly, pidManager)
+}
+
+/** Check if the daemon at the given port is responsive, initialized, and can serve MCP tools */
+async function isDaemonHealthy(port: number): Promise<boolean> {
+  try {
+    const healthRes = await fetch(`http://localhost:${port}/api/health`, {
+      signal: AbortSignal.timeout(2000),
+    })
+    const healthJson = await healthRes.json() as any
+    if (healthJson.success !== true || healthJson.initialized !== true) return false
+
+    // Verify MCP proxy endpoints actually work (old versions return 404)
+    const toolsRes = await fetch(`http://localhost:${port}/api/mcp/list-tools`, {
+      signal: AbortSignal.timeout(2000),
+    })
+    const toolsJson = await toolsRes.json() as any
+    return toolsJson.success === true && Array.isArray(toolsJson.data?.tools)
+  } catch {
+    return false
+  }
+}
+
+/** Run as thin MCP proxy — forward all MCP calls to daemon via HTTP */
+async function runAsProxy(daemonPort: number) {
+  const config = await loadConfig()
+  const logger = createLogger(config.logLevel, config.logFilePath)
+  const mainLogger = createComponentLogger(logger, 'proxy')
+
+  mainLogger.info({ daemonPort }, 'Starting as MCP proxy → daemon')
+
+  const { McpProxyServer } = await import('@/server/mcp-proxy')
+
+  let isStopping = false
+  const proxy = new McpProxyServer({
+    daemonUrl: `http://localhost:${daemonPort}`,
+    serverName: config.serverName,
+    serverVersion: config.serverVersion,
+    onStdinClose: () => {
+      if (isStopping) return
+      isStopping = true
+      mainLogger.info('stdin closed — proxy exiting')
+      proxy.stop().finally(() => process.exit(0))
+    },
+  })
+
+  const stopProxy = async (signal: string) => {
+    if (isStopping) return
+    isStopping = true
+    mainLogger.info({ signal }, 'Proxy shutting down')
+    await proxy.stop()
+    process.exit(0)
+  }
+
+  process.on('SIGTERM', () => stopProxy('SIGTERM'))
+  process.on('SIGINT', () => stopProxy('SIGINT'))
+  if (process.platform !== 'win32') {
+    process.on('SIGHUP', () => stopProxy('SIGHUP'))
+  }
+
+  await proxy.start()
+  mainLogger.info('MCP proxy ready — forwarding to daemon')
+}
+
+/** Run as full daemon with services, HTTP, and optionally MCP stdio */
+async function runAsDaemon(httpOnly: boolean, pidManager: ServerPidManager) {
+  // Auto-install Claude Code hooks (idempotent, non-fatal)
+  try {
+    const { installHooks } = await import('@/hooks/installer')
+    const hookResult = installHooks()
+    if (hookResult.message !== 'Hooks already installed') {
+      console.error(`[claude-brain] ${hookResult.message}`)
+    }
+  } catch (error) {
+    console.error(`[claude-brain] Hook auto-install skipped: ${error instanceof Error ? error.message : 'unknown error'}`)
+  }
+
+  // Auto-install shell auto-start if not already present
+  try {
+    const { isAutoStartInstalled, installAutoStart } = await import('@/cli/auto-start')
+    if (!isAutoStartInstalled()) {
+      const result = installAutoStart()
+      if (result.success && result.profilePath) {
+        console.error(`[claude-brain] Auto-start installed in ${result.profilePath}`)
+      }
+    }
+  } catch (error) {
+    // Non-fatal — auto-start is a convenience feature
+  }
+
+  // Auto-install CLAUDE.md if not present
+  try {
+    const { existsSync, readFileSync, writeFileSync, mkdirSync } = await import('node:fs')
+    const { join, resolve, dirname } = await import('node:path')
+    const { homedir } = await import('node:os')
+    const { fileURLToPath } = await import('node:url')
+    const claudeMdDest = join(homedir(), '.claude', 'CLAUDE.md')
+    const pkgRoot = resolve(dirname(fileURLToPath(import.meta.url)), '..', '..', '..')
+    const claudeMdSrc = join(pkgRoot, 'assets', 'CLAUDE.md')
+    if (existsSync(claudeMdSrc) && !existsSync(claudeMdDest)) {
+      mkdirSync(join(homedir(), '.claude'), { recursive: true })
+      writeFileSync(claudeMdDest, readFileSync(claudeMdSrc, 'utf-8'), 'utf-8')
+      console.error('[claude-brain] CLAUDE.md installed to ~/.claude/CLAUDE.md')
+    }
+  } catch {
+    // Non-fatal
+  }
+
+  const config = await loadConfig()
+
+  if (config.logLevel === 'debug' || config.logLevel === 'info') {
+    console.error(BANNER)
+  }
+
+  const logger = createLogger(config.logLevel, config.logFilePath)
+  const mainLogger = createComponentLogger(logger, 'main')
+
+  new GlobalErrorHandler(logger)
+  const cleanup = new CleanupManager(logger)
+
+  mainLogger.info({
+    serverName: config.serverName,
+    serverVersion: config.serverVersion,
+    vaultPath: config.vaultPath,
+    nodeEnv: config.nodeEnv
+  }, 'Claude Brain starting...')
+
+  mainLogger.info({
+    logLevel: config.logLevel,
+    enableFileWatch: config.enableFileWatch,
+    cacheSize: config.cacheSize
+  }, 'Configuration loaded')
+
+  // Only start ChromaDB if explicitly enabled in config
+  let chromaReady = false
+  if (config.chromadb?.enabled) {
+    mainLogger.info('ChromaDB enabled, ensuring it is available...')
+    const { ensureChromaRunning } = await import('@/cli/commands/chroma')
+    chromaReady = await ensureChromaRunning({ silent: process.env.NODE_ENV === 'production' })
+    mainLogger.info({ chromaReady }, chromaReady ? 'ChromaDB is ready' : 'ChromaDB not available, using SQLite fallback')
+  } else {
+    mainLogger.info('Using SQLite FTS5 storage (ChromaDB disabled)')
+  }
+
+  mainLogger.info('Initializing services...')
+  await initializeServices(config, logger)
+  mainLogger.info('Services initialized successfully')
+
+  // Initialize orchestrator for event-driven features
+  let orchestrator: Orchestrator | null = null
+  try {
+    const vault = getVaultService()
+    const memory = getMemoryService()
+
+    orchestrator = createOrchestrator(logger, vault, memory, {
+      maxConcurrentOperations: 5,
+      debounceMs: 5000
+    })
+
+    await orchestrator.initialize()
+    mainLogger.info('Orchestrator initialized successfully')
+  } catch (error) {
+    mainLogger.warn({ error }, 'Failed to initialize orchestrator, continuing without event-driven features')
+  }
+
+  const mcpServer = new ClaudeBrainMCPServer(config, logger, {
+    events: {
+      onConnectionStateChange: (state) => {
+        mainLogger.info({ state }, 'MCP connection state changed')
+      },
+      onError: (error) => {
+        mainLogger.error({ error: error.message }, 'MCP server error')
+      },
+      onRequest: (toolName, requestId) => {
+        pidManager.touchActivity()
+        mainLogger.debug({ toolName, requestId }, 'Tool request received')
+      },
+      onResponse: (toolName, requestId, durationMs) => {
+        mainLogger.debug({ toolName, requestId, durationMs }, 'Tool response sent')
+      }
+    }
+  })
+
+  cleanup.register(async () => {
+    await mcpServer.stop()
+  })
+
+  // Register orchestrator cleanup before services shutdown
+  if (orchestrator) {
+    cleanup.register(async () => {
+      orchestrator!.shutdown()
+      mainLogger.info('Orchestrator shut down')
+    })
+  }
+
+  cleanup.register(async () => {
+    await shutdownServices()
+  })
+
+  // ── Idempotent shutdown guard ────────────────────────────
+  let isShuttingDown = false
+  const shutdown = async (signal: string) => {
+    if (isShuttingDown) return
+    isShuttingDown = true
+    mainLogger.info({ signal }, 'Shutting down...')
+    await cleanup.cleanup()
+    process.exit(0)
+  }
+
+  // ── Primary daemon: HTTP server + background services ────
+  // Write PID file and register cleanup
+  pidManager.writePidFile(config.port)
+  pidManager.registerCleanupHandlers()
+
+  cleanup.register(async () => {
+    pidManager.cleanup()
+  })
+
+  // Start HTTP API server
+  const { HttpApiServer } = await import('@/server/http-api')
+  const httpServer = new HttpApiServer(config, logger)
+
+  // Wire activity tracker to PID manager for idle watchdog
+  httpServer.setActivityTracker(() => pidManager.touchActivity())
+
+  cleanup.register(async () => {
+    await httpServer.stop()
+  })
+
+  // Phase 21: Use session tracker from services
+  {
+    const { getSessionTracker } = await import('@/server/services')
+    const sessionTracker = getSessionTracker()
+    if (sessionTracker) {
+      httpServer.setSessionTracker(sessionTracker)
+      mainLogger.info('Session tracker wired to HTTP server')
+    }
+  }
+
+  // Phase 28: Wire code intelligence to HTTP server
+  {
+    const { getCodeIndexer, getCodeQuery } = await import('@/server/services')
+    const codeIndexer = getCodeIndexer()
+    const codeQuery = getCodeQuery()
+    if (codeIndexer && codeQuery) {
+      httpServer.setCodeIntelligence(codeIndexer, codeQuery)
+      mainLogger.info('Code intelligence wired to HTTP server')
+    }
+  }
+
+  // Phase 29: Wire code linker to HTTP server
+  {
+    const { getCodeLinker } = await import('@/server/services')
+    const codeLinker = getCodeLinker()
+    if (codeLinker) {
+      httpServer.setCodeLinker(codeLinker)
+      mainLogger.info('Code linker wired to HTTP server')
+    }
+  }
+
+  // Phase 30: Activity log pruning on startup + periodic cleanup
+  {
+    const memory = getMemoryService()
+    if (memory?.isInitialized()) {
+      try {
+        const { startPeriodicPruning } = await import('@/memory/pruning')
+        const db = memory.database.getDb()
+        const stopPruning = startPeriodicPruning(db, logger, 30)
+        cleanup.register(async () => {
+          stopPruning()
+          mainLogger.info('Activity log pruning stopped')
+        })
+        mainLogger.info('Activity log pruning initialized')
+      } catch (error) {
+        mainLogger.warn({ error }, 'Failed to initialize activity log pruning')
+      }
+    }
+  }
+
+  // Phase 30: Optional LLM compression
+  if (config.compression?.enabled) {
+    try {
+      const { ObservationCompressor } = await import('@/memory/compression')
+      const { getBrainRouter } = await import('@/routing/router')
+      const compressor = new ObservationCompressor(config.compression, logger)
+      const router = getBrainRouter(logger)
+      router.setCompressor(compressor)
+      mainLogger.info({ provider: config.compression.provider, model: config.compression.model }, 'LLM compression enabled')
+    } catch (error) {
+      mainLogger.warn({ error }, 'Failed to initialize LLM compression')
+    }
+  }
+
+  // Phase 31: Auto-update checker
+  let autoUpdater: InstanceType<typeof import('@/server/auto-updater').AutoUpdater> | null = null
+  if (config.autoUpdate?.enabled !== false) {
+    try {
+      const { AutoUpdater } = await import('@/server/auto-updater')
+      autoUpdater = new AutoUpdater(
+        {
+          enabled: config.autoUpdate?.enabled ?? true,
+          checkIntervalHours: config.autoUpdate?.checkIntervalHours ?? 24,
+          autoRestart: config.autoUpdate?.autoRestart ?? true,
+        },
+        mainLogger
+      )
+
+      // Check for updates on startup (non-blocking)
+      autoUpdater.check().then(result => {
+        if (result.updateAvailable && result.latestVersion) {
+          mainLogger.info(
+            { current: result.currentVersion, latest: result.latestVersion },
+            'Update available! Run: claude-brain update'
+          )
+        }
+      }).catch((error) => {
+        mainLogger.warn({ error }, 'Background auto-update check failed')
+      })
+
+      // Schedule periodic checks
+      autoUpdater.schedulePeriodicCheck()
+
+      cleanup.register(async () => {
+        autoUpdater?.stopPeriodicCheck()
+        mainLogger.info('Auto-updater stopped')
+      })
+
+      mainLogger.info('Auto-updater initialized')
+    } catch (error) {
+      mainLogger.warn({ error }, 'Failed to initialize auto-updater')
+    }
+  }
+
+  // Start HTTP server after MCP server is ready
+  setTimeout(async () => {
+    try {
+      await httpServer.start()
+      mainLogger.info({ port: config.port }, 'HTTP API server started')
+
+      // Drain hook queue after HTTP server is ready
+      try {
+        const { drainQueue } = await import('@/hooks/queue')
+        const drained = await drainQueue(config.port)
+        if (drained > 0) {
+          mainLogger.info({ drained }, 'Drained hook queue')
+        }
+      } catch (error) {
+        mainLogger.debug({ error }, 'No hook queue to drain')
+      }
+    } catch (error: unknown) {
+      // EADDRINUSE: kill the stale process and retry once
+      const errObj = error as Record<string, unknown>
+      if (errObj?.code === 'EADDRINUSE' || String(error).includes('EADDRINUSE')) {
+        mainLogger.warn({ port: config.port }, 'Port in use — killing stale process and retrying')
+        try {
+          const { killProcessOnPort } = await import('@/utils/kill-port')
+          const killed = killProcessOnPort(config.port)
+          if (killed.length > 0) {
+            mainLogger.info({ killed }, 'Killed stale process(es) on port')
+          }
+          await new Promise(r => setTimeout(r, 1000))
+          await httpServer.start()
+          mainLogger.info({ port: config.port }, 'HTTP API server started (after recovery)')
+
+          // Drain hook queue on retry success too
+          try {
+            const { drainQueue } = await import('@/hooks/queue')
+            const drained = await drainQueue(config.port)
+            if (drained > 0) {
+              mainLogger.info({ drained }, 'Drained hook queue')
+            }
+          } catch {}
+        } catch (retryError) {
+          mainLogger.error({ error: retryError }, 'Failed to start HTTP API server after recovery — MCP stdio still works')
+        }
+      } else {
+        mainLogger.error({ error }, 'Failed to start HTTP API server')
+      }
+    }
+  }, 2000)
+
+  // ── Signal handlers ──────────────────────────────────────
+  process.on('SIGTERM', () => shutdown('SIGTERM'))
+  process.on('SIGINT', () => shutdown('SIGINT'))
+  if (process.platform !== 'win32') {
+    process.on('SIGHUP', () => shutdown('SIGHUP'))
+  }
+
+  if (httpOnly) {
+    // HTTP-only daemon mode: no MCP stdio. Use idle watchdog instead of infinite keepAlive.
+    mainLogger.info('HTTP-only mode — MCP stdio disabled (background daemon)')
+
+    const idleTimeoutMs = (config.daemon?.idleTimeoutMinutes ?? 30) * 60 * 1000
+    if (idleTimeoutMs > 0) {
+      const watchdog = setInterval(() => {
+        const idleMs = pidManager.getIdleMs()
+        if (idleMs >= idleTimeoutMs) {
+          mainLogger.info({ idleMs, idleTimeoutMs }, 'Idle timeout reached — shutting down daemon')
+          clearInterval(watchdog)
+          shutdown('idle-timeout')
+        }
+      }, 60_000)
+      cleanup.register(async () => clearInterval(watchdog))
+      mainLogger.info({ idleTimeoutMinutes: config.daemon?.idleTimeoutMinutes ?? 30 }, 'Idle watchdog started')
+    } else {
+      // idleTimeoutMinutes=0 means never self-terminate (old behavior)
+      const keepAlive = setInterval(() => {}, 60_000 * 60)
+      cleanup.register(async () => clearInterval(keepAlive))
+      mainLogger.info('Idle watchdog disabled (idleTimeoutMinutes=0)')
+    }
+  } else {
+    // MCP stdio mode: start MCP server and detect stdin closure
+    await mcpServer.start()
+    mainLogger.info('Claude Brain MCP server ready and listening for connections')
+
+    // Detect stdin close — Claude Code disconnected
+    process.stdin.on('end', () => shutdown('stdin-end'))
+    process.stdin.on('close', () => shutdown('stdin-close'))
+  }
+}