@pellux/goodvibes-tui 0.18.4

package/src/runtime/lifecycle.ts

@@ -0,0 +1,107 @@
+/**
+ * Lifecycle management for the goodvibes-tui runtime.
+ *
+ * Handles ordered teardown: persist session, fire lifecycle hooks,
+ * stop background managers. Terminal teardown remains in main.ts.
+ */
+import type { HookDispatcher } from '../hooks/index.ts';
+import type { HookPhase, HookCategory, HookEventPath } from '@pellux/goodvibes-sdk/platform/hooks/types';
+import type { ScheduleManager } from '@pellux/goodvibes-sdk/platform/tools/workflow/index';
+import type { ProviderRegistry } from '../providers/registry.ts';
+import { logger } from '@pellux/goodvibes-sdk/platform/utils/logger';
+export { saveSession } from './session-persistence.ts';
+import { saveSession, type SessionPersistenceOptions, type SessionSnapshot } from './session-persistence.ts';
+import type { CrossSessionTaskRegistry } from '@pellux/goodvibes-sdk/platform/sessions/orchestration/index';
+import { summarizeError } from '@pellux/goodvibes-sdk/platform/utils/error-display';
+
+// ── Startup lifecycle ────────────────────────────────────────────────────────
+
+/**
+ * Fire the session:start lifecycle hook.
+ * Non-fatal: errors are logged and swallowed.
+ */
+export function fireSessionStart(
+  sessionId: string,
+  hookDispatcher: Pick<HookDispatcher, 'fire'> | null,
+): void {
+  if (!hookDispatcher) return;
+  try {
+    hookDispatcher.fire({
+      path: 'Lifecycle:session:start' as HookEventPath,
+      phase: 'Lifecycle' as HookPhase,
+      category: 'session' as HookCategory,
+      specific: 'start',
+      sessionId,
+      timestamp: Date.now(),
+      payload: { sessionId },
+    }).catch((err: unknown) => {
+      logger.debug('fireSessionStart hook error (non-fatal)', { error: summarizeError(err) });
+    });
+  } catch (err) {
+    logger.debug('fireSessionStart sync error (non-fatal)', { error: summarizeError(err) });
+  }
+}
+
+// ── Shutdown lifecycle ───────────────────────────────────────────────────────
+
+/**
+ * Ordered logical shutdown of all background runtime subsystems.
+ *
+ * Sequence:
+ * 1. Persist conversation to sessions store
+ * 2. Fire session:end and session:save lifecycle hooks
+ * 3. Destroy ScheduleManager (cancels pending scheduled tasks)
+ * 4. Stop provider registry file-watcher
+ *
+ * This function does NOT touch the terminal (alt-screen, raw mode, etc.) —
+ * that remains the responsibility of main.ts.
+ *
+ * @param sessionId  - Active session identifier.
+ * @param sessionData - Latest conversation to persist.
+ * @param model      - Active model identifier.
+ * @param provider   - Active provider identifier.
+ * @param title      - Conversation title (may be empty string).
+ */
+export async function shutdownRuntime(
+  sessionId: string,
+  sessionData: SessionSnapshot,
+  model: string,
+  provider: string,
+  title = '',
+  scheduleManager?: ScheduleManager | null,
+  hookDispatcher?: Pick<HookDispatcher, 'fire'> | null,
+  providerRegistry?: Pick<ProviderRegistry, 'stopWatching'> | null,
+  sessionOrchestration?: Pick<CrossSessionTaskRegistry, 'dispose'> | null,
+  persistenceOptions?: SessionPersistenceOptions,
+): Promise<void> {
+  // Step 1: persist conversation
+  saveSession(sessionId, sessionData, model, provider, title, persistenceOptions);
+
+  // Step 2: lifecycle hooks (fire-and-forget, best-effort before process exit)
+  const fireHook = (specific: string): void => {
+    if (!hookDispatcher) return;
+    try {
+      hookDispatcher.fire({
+        path: `Lifecycle:session:${specific}` as HookEventPath,
+        phase: 'Lifecycle' as HookPhase,
+        category: 'session' as HookCategory,
+        specific,
+        sessionId,
+        timestamp: Date.now(),
+        payload: { sessionId },
+      }).catch((err: unknown) => { logger.debug('shutdownRuntime hook fire error (non-fatal)', { specific, error: summarizeError(err) }); });
+    } catch (err) { logger.debug('shutdownRuntime hook sync error (non-fatal)', { specific, error: summarizeError(err) }); }
+  };
+
+  fireHook('end');
+  fireHook('save');
+
+  // Step 3: stop ScheduleManager
+  try { scheduleManager?.destroy(); } catch (err) { logger.debug('ScheduleManager.destroy failed (non-fatal)', { error: summarizeError(err) }); }
+
+  // Step 4: stop provider registry watcher
+  try { providerRegistry?.stopWatching(); } catch (err) { logger.debug('providerRegistry.stopWatching failed (non-fatal)', { error: summarizeError(err) }); }
+
+  // Step 5: dispose cross-session orchestration registry if it is app-owned in this runtime
+  try { sessionOrchestration?.dispose(); } catch (err) { logger.debug('sessionOrchestration.dispose failed (non-fatal)', { error: summarizeError(err) }); }
+}

package/src/runtime/mcp/index.ts

@@ -0,0 +1,68 @@
+/**
+ * src/runtime/mcp — MCP lifecycle barrel.
+ *
+ * Gated by the `mcp-lifecycle` feature flag.
+ *
+ * Public API:
+ *   - `createMcpLifecycleManager()` — factory function
+ *   - All types from types.ts
+ *   - State machine helpers from lifecycle.ts
+ *   - Permission manager from permissions.ts
+ *   - Schema freshness tracker from schema-freshness.ts
+ *   - Manager from manager.ts
+ */
+
+export { McpLifecycleManager, type McpEventHandler, type McpLifecycleManagerOptions } from './manager.ts';
+export { McpPermissionManager, buildMcpAttackPathReview } from '@pellux/goodvibes-sdk/platform/runtime/mcp/permissions';
+export { McpSchemaFreshnessTracker } from '@pellux/goodvibes-sdk/platform/runtime/mcp/schema-freshness';
+export {
+  canTransition,
+  reachableFrom,
+  applyTransition,
+  isOperational,
+  isTerminal,
+  type TransitionResult,
+} from '@pellux/goodvibes-sdk/platform/runtime/mcp/lifecycle';
+export type {
+  McpServerState,
+  SchemaFreshness,
+  McpSchemaRecord,
+  QuarantineReason,
+  QuarantineRecord,
+  McpTrustLevel,
+  McpTrustMode,
+  McpServerRole,
+  McpCapabilityClass,
+  McpCoherenceVerdict,
+  McpRiskLevel,
+  McpPermission,
+  McpTrustProfile,
+  McpCoherenceAssessment,
+  McpDecisionRecord,
+  McpSecuritySnapshot,
+  McpAttackPathFindingKind,
+  McpAttackPathFinding,
+  McpAttackPathReview,
+  McpToolPermission,
+  McpServerPermissions,
+  McpServerEntry,
+  McpReconnectConfig,
+} from '@pellux/goodvibes-sdk/platform/runtime/mcp/types';
+export { DEFAULT_RECONNECT_CONFIG } from '@pellux/goodvibes-sdk/platform/runtime/mcp/types';
+
+import { McpLifecycleManager } from './manager.ts';
+import type { McpLifecycleManagerOptions } from './manager.ts';
+
+/**
+ * Factory function for creating a `McpLifecycleManager`.
+ *
+ * Check the `mcp-lifecycle` feature flag before calling this — when the
+ * flag is disabled, the caller should use the standard MCP registry path.
+ *
+ * @param options - Optional configuration overrides
+ */
+export function createMcpLifecycleManager(
+  options?: McpLifecycleManagerOptions,
+): McpLifecycleManager {
+  return new McpLifecycleManager(options);
+}

package/src/runtime/mcp/manager.ts

@@ -0,0 +1,513 @@
+/**
+ * McpLifecycleManager — drives the MCP server state machine.
+ *
+ * Gated by the `mcp-lifecycle` feature flag. When the flag is disabled
+ * callers should use the standard MCP registry path instead.
+ *
+ * Responsibilities:
+ *   - Track per-server McpServerEntry state
+ *   - Orchestrate McpClient connect/disconnect
+ *   - Drive lifecycle state transitions via lifecycle.ts
+ *   - Emit McpEvent on every transition
+ *   - Schedule reconnects with exponential back-off
+ *   - Delegate permission checks to McpPermissionManager
+ *   - Delegate schema freshness to McpSchemaFreshnessTracker
+ */
+import { logger } from '@pellux/goodvibes-sdk/platform/utils/logger';
+import { McpClient } from '../../mcp/client.ts';
+import type { McpServerConfig } from '@pellux/goodvibes-sdk/platform/mcp/config';
+import type { McpEvent } from '@pellux/goodvibes-sdk/platform/runtime/events/mcp';
+import {
+  applyTransition,
+  isOperational,
+} from '@pellux/goodvibes-sdk/platform/runtime/mcp/lifecycle';
+import { McpPermissionManager } from '@pellux/goodvibes-sdk/platform/runtime/mcp/permissions';
+import { McpSchemaFreshnessTracker } from '@pellux/goodvibes-sdk/platform/runtime/mcp/schema-freshness';
+import type {
+  McpServerState,
+  McpServerEntry,
+  McpReconnectConfig,
+  McpTrustLevel,
+  McpPermission,
+  SchemaFreshness,
+  QuarantineReason,
+  McpTrustMode,
+  McpServerRole,
+  McpServerPermissions,
+} from '@pellux/goodvibes-sdk/platform/runtime/mcp/types';
+import { DEFAULT_RECONNECT_CONFIG } from '@pellux/goodvibes-sdk/platform/runtime/mcp/types';
+import { summarizeError } from '@pellux/goodvibes-sdk/platform/utils/error-display';
+
+/** Callback type for state-change notifications. */
+export type McpEventHandler = (event: McpEvent) => void;
+
+// ── Factory ───────────────────────────────────────────────────────────────────
+
+/** Options for constructing a McpLifecycleManager. */
+export interface McpLifecycleManagerOptions {
+  /** Reconnect back-off configuration. Defaults to DEFAULT_RECONNECT_CONFIG. */
+  reconnect?: Partial<McpReconnectConfig>;
+  /** Schema freshness TTL in ms. Defaults to 5 minutes. */
+  schemaTtlMs?: number;
+}
+
+// ── Manager ───────────────────────────────────────────────────────────────────
+
+/**
+ * McpLifecycleManager — manages the full lifecycle of all configured MCP servers.
+ *
+ * Usage:
+ * ```ts
+ * const mgr = createMcpLifecycleManager();
+ * mgr.onEvent((e) => store.dispatch(e));
+ * await mgr.startAll(configs);
+ * // ...
+ * await mgr.stopAll();
+ * ```
+ */
+export class McpLifecycleManager {
+  private readonly servers = new Map<string, McpServerEntry>();
+  private readonly clients = new Map<string, McpClient>();
+  private readonly permissions: McpPermissionManager;
+  private readonly freshness: McpSchemaFreshnessTracker;
+  private readonly reconnectConfig: McpReconnectConfig;
+  private readonly eventHandlers: McpEventHandler[] = [];
+  private readonly reconnectTimers = new Map<string, ReturnType<typeof setTimeout>>();
+
+  constructor(options: McpLifecycleManagerOptions = {}) {
+    this.reconnectConfig = {
+      ...DEFAULT_RECONNECT_CONFIG,
+      ...options.reconnect,
+    };
+    this.permissions = new McpPermissionManager();
+    this.freshness = new McpSchemaFreshnessTracker(options.schemaTtlMs);
+  }
+
+  // ── Event subscription ────────────────────────────────────────────────────
+
+  /**
+   * Register an event handler called on every lifecycle transition.
+   *
+   * @param handler - Callback receiving McpEvent on each transition
+   */
+  onEvent(handler: McpEventHandler): void {
+    this.eventHandlers.push(handler);
+  }
+
+  // ── Server management ─────────────────────────────────────────────────────
+
+  /**
+   * Register and start all provided server configs.
+   *
+   * Connection errors on individual servers are logged but do not abort the
+   * overall startup.
+   *
+   * @param configs - Array of server configurations to start
+   */
+  async startAll(configs: McpServerConfig[]): Promise<void> {
+    await Promise.allSettled(configs.map((c) => this._startServer(c)));
+  }
+
+  /**
+   * Register and start a single server.
+   *
+   * @param config - Server configuration
+   */
+  async startServer(config: McpServerConfig): Promise<void> {
+    await this._startServer(config);
+  }
+
+  /**
+   * Disconnect all servers and cancel pending reconnect timers.
+   */
+  async stopAll(): Promise<void> {
+    const names = Array.from(this.servers.keys());
+    await Promise.allSettled(names.map((n) => this._stopServer(n, 'stopAll called')));
+  }
+
+  /**
+   * Disconnect a single server by name.
+   *
+   * @param serverName - Server identifier
+   * @param reason     - Optional reason for disconnection
+   */
+  async stopServer(serverName: string, reason?: string): Promise<void> {
+    await this._stopServer(serverName, reason);
+  }
+
+  // ── Permission delegation ─────────────────────────────────────────────────
+
+  /**
+   * Check whether a tool call is permitted for the given server.
+   *
+   * Quarantined schemas unconditionally block execution — the freshness check
+   * runs before the permission check so a quarantined schema cannot be bypassed
+   * by a permissive trust level.
+   *
+   * @param serverName - Server identifier
+   * @param toolName   - Tool name on the server (not qualified)
+   */
+  isToolAllowed(serverName: string, toolName: string): McpPermission {
+    if (this.freshness.isQuarantined(serverName)) {
+      const record = this.freshness.getRecord(serverName);
+      const detail = record?.quarantine?.detail ?? 'schema is quarantined';
+      return {
+        allowed: false,
+        reason: `Schema quarantined (${record?.quarantine?.reason ?? 'unknown'}): ${detail}. Refresh schema or request operator approval to proceed.`,
+      };
+    }
+    return this.permissions.isToolAllowed(serverName, toolName);
+  }
+
+  /**
+   * Update the trust level for a server.
+   *
+   * @param serverName - Server identifier
+   * @param level      - New trust level
+   */
+  setTrustLevel(serverName: string, level: McpTrustLevel): void {
+    this.permissions.setTrustLevel(serverName, level);
+  }
+
+  setTrustMode(serverName: string, mode: McpTrustMode): void {
+    this.permissions.setTrustMode(serverName, mode);
+  }
+
+  setServerRole(serverName: string, role: McpServerRole): void {
+    this.permissions.setServerRole(serverName, role);
+  }
+
+  /**
+   * Explicitly allow a tool for a server.
+   *
+   * @param serverName - Server identifier
+   * @param toolName   - Tool name
+   * @param note       - Optional note
+   */
+  allowTool(serverName: string, toolName: string, note?: string): void {
+    this.permissions.allowTool(serverName, toolName, note);
+  }
+
+  /**
+   * Explicitly deny a tool for a server.
+   *
+   * @param serverName - Server identifier
+   * @param toolName   - Tool name
+   * @param note       - Optional note
+   */
+  denyTool(serverName: string, toolName: string, note?: string): void {
+    this.permissions.denyTool(serverName, toolName, note);
+  }
+
+  getServerPermissions(serverName: string): McpServerPermissions | null {
+    return this.permissions.getServerPermissions(serverName);
+  }
+
+  listTrustProfiles(): Array<McpServerPermissions['profile']> {
+    return this.permissions.listProfiles();
+  }
+
+  // ── Schema freshness ──────────────────────────────────────────────────────
+
+  /**
+   * Return the schema freshness for a server.
+   *
+   * @param serverName - Server identifier
+   */
+  getSchemaFreshness(serverName: string): SchemaFreshness {
+    return this.freshness.getFreshness(serverName);
+  }
+
+  /**
+   * Returns `true` if the server's schema is quarantined.
+   *
+   * When quarantined, `isToolAllowed` will block all tool execution until the
+   * schema is refreshed (`markFresh` via a successful schema fetch) or an
+   * operator approves a temporary override via `approveSchemaQuarantine`.
+   *
+   * @param serverName - Server identifier
+   */
+  isSchemaQuarantined(serverName: string): boolean {
+    return this.freshness.isQuarantined(serverName);
+  }
+
+  /**
+   * Manually quarantine a server's schema.
+   *
+   * Intended for operator-initiated quarantine (e.g. after detecting schema
+   * incompatibility). Emits `MCP_SCHEMA_QUARANTINED`.
+   *
+   * @param serverName - Server identifier
+   * @param reason     - Why quarantine is being applied
+   * @param detail     - Optional detail for the MCP panel display
+   */
+  quarantineSchema(
+    serverName: string,
+    reason: QuarantineReason,
+    detail?: string,
+  ): void {
+    this.freshness.markQuarantined(serverName, reason, detail);
+    this._emit({
+      type: 'MCP_SCHEMA_QUARANTINED',
+      serverId: serverName,
+      reason,
+      detail,
+    });
+    logger.warn('McpLifecycleManager: schema quarantined', { server: serverName, reason, detail });
+  }
+
+  /**
+   * Operator override: approve a quarantined schema so tool execution can
+   * proceed temporarily without a full schema refresh.
+   *
+   * The quarantine record is preserved for audit purposes. Freshness transitions
+   * to `stale`. Emits `MCP_SCHEMA_QUARANTINE_APPROVED`.
+   *
+   * @param serverName - Server identifier
+   * @param operatorId - Identifier of the approving operator
+   */
+  approveSchemaQuarantine(serverName: string, operatorId: string): void {
+    if (!this.freshness.isQuarantined(serverName)) {
+      logger.debug('McpLifecycleManager: approveSchemaQuarantine called but not quarantined', { server: serverName });
+      return;
+    }
+    this.freshness.approveQuarantine(serverName, operatorId);
+    this._emit({
+      type: 'MCP_SCHEMA_QUARANTINE_APPROVED',
+      serverId: serverName,
+      operatorId,
+    });
+    logger.warn('McpLifecycleManager: quarantine override approved', { server: serverName, operatorId });
+  }
+
+  // ── Inspection ────────────────────────────────────────────────────────────
+
+  /** Return the current lifecycle state for a server, or `null` if unknown. */
+  getState(serverName: string): McpServerState | null {
+    return this.servers.get(serverName)?.state ?? null;
+  }
+
+  /** Return all server entries as a read-only snapshot. */
+  getServers(): ReadonlyMap<string, McpServerEntry> {
+    return this.servers;
+  }
+
+  /** Return the entry for a single server, or `null`. */
+  getServer(serverName: string): McpServerEntry | null {
+    return this.servers.get(serverName) ?? null;
+  }
+
+  /** Names of all servers currently in an operational state (connected/degraded). */
+  get operationalServerNames(): string[] {
+    return Array.from(this.servers.entries())
+      .filter(([, entry]) => isOperational(entry.state))
+      .map(([name]) => name);
+  }
+
+  // ── Private: start ────────────────────────────────────────────────────────
+
+  private async _startServer(config: McpServerConfig): Promise<void> {
+    const { name } = config;
+
+    if (this.servers.has(name)) {
+      logger.info('McpLifecycleManager: server already registered', { name });
+      return;
+    }
+
+    // Register in subsystems
+    this.permissions.registerServer(name, 'standard', {
+      role: config.role ?? 'general',
+      mode: config.trustMode ?? 'ask-on-risk',
+      allowedPaths: config.allowedPaths ?? [],
+      allowedHosts: config.allowedHosts ?? [],
+    });
+    this.freshness.registerServer(name);
+
+    // Create entry in configured state
+    const entry: McpServerEntry = {
+      name,
+      config,
+      state: 'configured',
+      reconnectAttempts: 0,
+      reconnectPending: false,
+      availableTools: [],
+      availableResources: [],
+      callCount: 0,
+      errorCount: 0,
+    };
+    this.servers.set(name, entry);
+    this._emit({ type: 'MCP_CONFIGURED', serverId: name, transport: 'stdio' });
+
+    // Begin connection attempt
+    await this._connect(name);
+  }
+
+  private async _connect(serverName: string): Promise<void> {
+    const entry = this.servers.get(serverName);
+    if (!entry) return;
+
+    const toConnecting = applyTransition(entry.state, 'connecting');
+    if (!toConnecting.success) {
+      logger.debug('McpLifecycleManager: cannot transition to connecting', {
+        server: serverName,
+        reason: toConnecting.reason,
+      });
+      return;
+    }
+    this._setState(entry, 'connecting');
+    this._emit({ type: 'MCP_CONNECTING', serverId: serverName });
+
+    try {
+      const client = new McpClient(entry.config);
+      await client.connect();
+      this.clients.set(serverName, client);
+
+      // Load tool list
+      const tools = await client.listTools().catch((err: unknown) => {
+        logger.debug('McpLifecycleManager: listTools failed', { server: serverName, err: summarizeError(err) });
+        return [];
+      });
+      entry.availableTools = tools.map((t) => t.name);
+
+      entry.connectedAt = Date.now();
+      entry.reconnectAttempts = 0;
+      entry.reconnectPending = false;
+
+      this._setState(entry, 'connected');
+      this.freshness.markStale(serverName); // invalidate on (re)connect
+
+      this._emit({
+        type: 'MCP_CONNECTED',
+        serverId: serverName,
+        toolCount: entry.availableTools.length,
+        resourceCount: entry.availableResources.length,
+      });
+
+      logger.info('McpLifecycleManager: server connected', {
+        server: serverName,
+        tools: entry.availableTools.length,
+      });
+    } catch (err) {
+      const message = summarizeError(err);
+      entry.lastError = message;
+      logger.error('McpLifecycleManager: connection failed', { server: serverName, err: message });
+      this._scheduleReconnect(serverName);
+    }
+  }
+
+  // ── Private: stop ─────────────────────────────────────────────────────────
+
+  private async _stopServer(serverName: string, reason?: string): Promise<void> {
+    this._cancelReconnect(serverName);
+
+    const entry = this.servers.get(serverName);
+    if (!entry) return;
+
+    const client = this.clients.get(serverName);
+    if (client) {
+      try {
+        await client.disconnect();
+      } catch (err) {
+        // Non-fatal — we are stopping regardless
+        logger.debug('McpLifecycleManager: disconnect error (suppressed)', { server: serverName, err: summarizeError(err) });
+      }
+      this.clients.delete(serverName);
+    }
+
+    entry.disconnectedAt = Date.now();
+    entry.lastError = reason;
+    this._setState(entry, 'disconnected');
+    this._emit({ type: 'MCP_DISCONNECTED', serverId: serverName, reason, willRetry: false });
+  }
+
+  // ── Private: reconnect ────────────────────────────────────────────────────
+
+  private _scheduleReconnect(serverName: string): void {
+    const entry = this.servers.get(serverName);
+    if (!entry) return;
+
+    if (entry.reconnectAttempts >= this.reconnectConfig.maxAttempts) {
+      logger.info('McpLifecycleManager: max reconnect attempts reached', {
+        server: serverName,
+        attempts: entry.reconnectAttempts,
+      });
+      entry.disconnectedAt = Date.now();
+      this._setState(entry, 'disconnected');
+      this._emit({
+        type: 'MCP_DISCONNECTED',
+        serverId: serverName,
+        reason: `max reconnect attempts (${this.reconnectConfig.maxAttempts}) exceeded`,
+        willRetry: false,
+      });
+      return;
+    }
+
+    const attempt = entry.reconnectAttempts + 1;
+    const delay = Math.min(
+      this.reconnectConfig.baseDelayMs * Math.pow(2, attempt - 1),
+      this.reconnectConfig.maxDelayMs,
+    );
+
+    this._setState(entry, 'reconnecting');
+    entry.reconnectPending = true;
+    entry.reconnectAttempts = attempt;
+
+    this._emit({
+      type: 'MCP_RECONNECTING',
+      serverId: serverName,
+      attempt,
+      maxAttempts: this.reconnectConfig.maxAttempts,
+    });
+
+    logger.info('McpLifecycleManager: scheduling reconnect', { server: serverName, attempt, delayMs: delay });
+
+    const timer = setTimeout(() => {
+      this.reconnectTimers.delete(serverName);
+      const current = this.servers.get(serverName);
+      if (!current || current.state !== 'reconnecting') return;
+      current.reconnectPending = false;
+      void this._connect(serverName);
+    }, delay);
+
+    this.reconnectTimers.set(serverName, timer);
+  }
+
+  private _cancelReconnect(serverName: string): void {
+    const timer = this.reconnectTimers.get(serverName);
+    if (timer !== undefined) {
+      clearTimeout(timer);
+      this.reconnectTimers.delete(serverName);
+      const entry = this.servers.get(serverName);
+      if (entry) entry.reconnectPending = false;
+    }
+  }
+
+  // ── Private: state helpers ────────────────────────────────────────────────
+
+  private _setState(entry: McpServerEntry, next: McpServerState): void {
+    const result = applyTransition(entry.state, next);
+    if (!result.success) {
+      logger.debug('McpLifecycleManager: invalid transition (ignored)', {
+        server: entry.name,
+        from: entry.state,
+        to: next,
+        reason: result.reason,
+      });
+      return;
+    }
+    entry.state = next;
+  }
+
+  // ── Private: event emission ───────────────────────────────────────────────
+
+  private _emit(event: McpEvent): void {
+    for (const handler of this.eventHandlers) {
+      try {
+        handler(event);
+      } catch (err) {
+        // Non-fatal: handler errors must not crash the manager
+        logger.debug('McpLifecycleManager: event handler threw', { event: event.type, err: summarizeError(err) });
+      }
+    }
+  }
+}