@codemation/host 0.5.1 → 0.7.0

package/src/bootstrap/perf/BootTimer.ts

@@ -0,0 +1,168 @@
+/**
+ * Lightweight boot-phase timer. Designed for diagnosing slow `pnpm dev` cold starts.
+ *
+ * Usage: every meaningful boot phase wraps its async work in
+ *   `await BootTimer.measureAsync("phase.name", async () => { ... })`
+ * (or the sync `measure` for non-async work). When `--trace-boot` is set on the CLI
+ * the timer records each phase in a tree, prints a pretty tree to stderr at the end
+ * of boot, and writes the same tree to `tmp/boot-trace.json` for diffing later.
+ *
+ * When disabled (default), every method is a near-zero-cost passthrough — no allocation,
+ * no Date.now() calls, no tree construction. Safe to leave instrumentation in production
+ * code paths.
+ */
+
+import { promises as fs } from "node:fs";
+import path from "node:path";
+
+type PhaseNode = {
+  name: string;
+  startNs: bigint;
+  endNs: bigint | null;
+  children: PhaseNode[];
+  parent: PhaseNode | null;
+};
+
+export type BootTracePhase = Readonly<{
+  name: string;
+  ms: number;
+  pct: number;
+  children: ReadonlyArray<BootTracePhase>;
+}>;
+
+export class BootTimer {
+  private static enabled = false;
+  private static root: PhaseNode | null = null;
+  private static current: PhaseNode | null = null;
+
+  /** Enable boot tracing for the lifetime of the current process. Idempotent. */
+  static enable(): void {
+    if (this.enabled) return;
+    this.enabled = true;
+    this.root = { name: "boot", startNs: process.hrtime.bigint(), endNs: null, children: [], parent: null };
+    this.current = this.root;
+  }
+
+  static isEnabled(): boolean {
+    return this.enabled;
+  }
+
+  /** Wrap an async phase. Pass-through when disabled. */
+  static async measureAsync<T>(name: string, fn: () => Promise<T>): Promise<T> {
+    if (!this.enabled || !this.current) {
+      return await fn();
+    }
+    const node = this.pushPhase(name);
+    try {
+      return await fn();
+    } finally {
+      this.popPhase(node);
+    }
+  }
+
+  /** Wrap a sync phase. Pass-through when disabled. */
+  static measure<T>(name: string, fn: () => T): T {
+    if (!this.enabled || !this.current) {
+      return fn();
+    }
+    const node = this.pushPhase(name);
+    try {
+      return fn();
+    } finally {
+      this.popPhase(node);
+    }
+  }
+
+  /**
+   * Manual start/stop for fire-and-forget phases (e.g. a spawned child process you only
+   * stop once a readiness probe succeeds). Returns the stop function.
+   */
+  static start(name: string): () => void {
+    if (!this.enabled || !this.current) {
+      return () => {};
+    }
+    const node = this.pushPhase(name);
+    return () => this.popPhase(node);
+  }
+
+  /** Print the tree to stderr and write JSON to the given path. Finalizes the root span. */
+  static async finish(outputJsonPath?: string): Promise<void> {
+    if (!this.enabled || !this.root) return;
+    if (this.root.endNs === null) {
+      this.root.endNs = process.hrtime.bigint();
+    }
+    const totalMs = nodeMs(this.root);
+    process.stderr.write(`\n=== Boot trace (total ${totalMs.toFixed(0)}ms) ===\n`);
+    writeTree(this.root, 0, totalMs);
+    process.stderr.write("=========================================\n\n");
+    if (outputJsonPath) {
+      try {
+        await fs.mkdir(path.dirname(outputJsonPath), { recursive: true });
+        await fs.writeFile(outputJsonPath, JSON.stringify(this.snapshot(), null, 2), "utf8");
+      } catch (error) {
+        process.stderr.write(`[boot-timer] failed to write JSON trace: ${String(error)}\n`);
+      }
+    }
+  }
+
+  /** Return a plain-object snapshot of the current tree (for tests / diffing). */
+  static snapshot(): BootTracePhase {
+    if (!this.root) {
+      return { name: "boot", ms: 0, pct: 100, children: [] };
+    }
+    const totalMs = nodeMs(this.root);
+    return toReport(this.root, totalMs);
+  }
+
+  /** Test helper: reset all state. Do not call in production code. */
+  static reset(): void {
+    this.enabled = false;
+    this.root = null;
+    this.current = null;
+  }
+
+  private static pushPhase(name: string): PhaseNode {
+    const node: PhaseNode = {
+      name,
+      startNs: process.hrtime.bigint(),
+      endNs: null,
+      children: [],
+      parent: this.current,
+    };
+    this.current!.children.push(node);
+    this.current = node;
+    return node;
+  }
+
+  private static popPhase(node: PhaseNode): void {
+    node.endNs = process.hrtime.bigint();
+    this.current = node.parent ?? this.root;
+  }
+}
+
+function nodeMs(node: PhaseNode): number {
+  const end = node.endNs ?? node.startNs;
+  return Number(end - node.startNs) / 1e6;
+}
+
+function toReport(node: PhaseNode, totalMs: number): BootTracePhase {
+  const ms = nodeMs(node);
+  return {
+    name: node.name,
+    ms,
+    pct: totalMs > 0 ? (ms / totalMs) * 100 : 0,
+    children: node.children.map((child) => toReport(child, totalMs)),
+  };
+}
+
+function writeTree(node: PhaseNode, depth: number, totalMs: number): void {
+  const ms = nodeMs(node);
+  const pct = totalMs > 0 ? ((ms / totalMs) * 100).toFixed(1) : "—";
+  const indent = "  ".repeat(depth);
+  const msStr = ms.toFixed(0).padStart(6);
+  const pctStr = pct.padStart(5);
+  process.stderr.write(`${indent}${msStr}ms  ${pctStr}%  ${node.name}\n`);
+  for (const child of node.children) {
+    writeTree(child, depth + 1, totalMs);
+  }
+}

package/src/bootstrap/runtime/AppConfigFactory.ts

@@ -1,17 +1,18 @@
 import { CoreTokens } from "@codemation/core";
-import type { AppConfig, AppPluginLoadSummary } from "../../presentation/config/AppConfig";
+import type { AppConfig, AppPersistenceConfig, AppPluginLoadSummary } from "../../presentation/config/AppConfig";
 import { CodemationPluginPackageMetadata } from "../../presentation/config/CodemationPlugin";
 import type { NormalizedCodemationConfig } from "../../presentation/config/CodemationConfigNormalizer";
 import type {
   CodemationApplicationRuntimeConfig,
-  CodemationDatabaseKind,
   CodemationEventBusKind,
   CodemationSchedulerKind,
 } from "../../presentation/config/CodemationConfig";
+import { CodemationDatabaseUrlParser } from "../../infrastructure/persistence/CodemationDatabaseUrlParser";
 import path from "node:path";
 
 export class AppConfigFactory {
   private readonly pluginPackageMetadata = new CodemationPluginPackageMetadata();
+  private readonly databaseUrlParser = new CodemationDatabaseUrlParser();
 
   create(
     args: Readonly<{
@@ -23,7 +24,7 @@ export class AppConfigFactory {
     }>,
   ): AppConfig {
     const runtimeConfig = args.config.runtime ?? {};
-    const persistence = this.resolvePersistence(runtimeConfig, args.env, args.consumerRoot);
+    const persistence = this.resolvePersistence(args.env, args.consumerRoot);
     const redisUrl = runtimeConfig.eventBus?.redisUrl ?? args.env.REDIS_URL;
     const schedulerKind = this.resolveSchedulerKind(runtimeConfig, args.env, redisUrl);
     const eventBusKind = this.resolveEventBusKind(runtimeConfig, args.env, schedulerKind, redisUrl);
@@ -46,12 +47,11 @@ export class AppConfigFactory {
       collections: [...(args.config.collections ?? [])],
       plugins,
       pluginLoadSummary: this.createConfiguredPluginLoadSummary(plugins),
+      mcpServers: [...(args.config.mcpServers ?? [])],
       hasConfiguredCredentialSessionServiceRegistration,
       log: args.config.log,
       engineExecutionLimits: runtimeConfig.engineExecutionLimits,
-      databaseUrl:
-        persistence.kind === "postgresql" ? persistence.databaseUrl : runtimeConfig.database?.url?.trim() || undefined,
-      database: runtimeConfig.database,
+      databaseUrl: persistence.kind === "postgresql" ? persistence.databaseUrl : undefined,
       persistence,
       scheduler: {
         kind: schedulerKind,
@@ -86,71 +86,27 @@ export class AppConfigFactory {
     return summaries;
   }
 
-  private resolvePersistence(
-    runtimeConfig: CodemationApplicationRuntimeConfig,
-    env: NodeJS.ProcessEnv,
-    consumerRoot: string,
-  ): AppConfig["persistence"] {
-    const database = runtimeConfig.database;
-    if (!database) {
-      return { kind: "none" };
-    }
-    const kind = this.resolveDatabaseKind(database.kind, database.url, env);
-    if (kind === "postgresql") {
-      const databaseUrl = database.url?.trim() ?? "";
-      if (!databaseUrl) {
-        throw new Error('runtime.database.kind is "postgresql" but no database URL was set (runtime.database.url).');
-      }
-      if (!databaseUrl.startsWith("postgresql://") && !databaseUrl.startsWith("postgres://")) {
-        throw new Error(
-          `runtime.database.url must be a postgresql:// or postgres:// URL when kind is postgresql. Received: ${databaseUrl}`,
-        );
-      }
-      return { kind: "postgresql", databaseUrl };
+  /**
+   * Database persistence is resolved exclusively from `CODEMATION_DATABASE_URL` (DSN format).
+   * Supported schemes: `sqlite://`, `pgsql://`, `postgresql://`, `postgres://`. When the env
+   * var is absent we default to a project-local SQLite file at
+   * `<consumerRoot>/.codemation/codemation.sqlite` — convenient for dev, explicit for prod.
+   *
+   * Config-based DB settings (`runtime.database` in codemation.config.ts) are intentionally
+   * not supported: keeping the resolver env-only lets the CLI skip the entire ~9s consumer
+   * config load on the migrations path and lets ops swap databases without touching code.
+   */
+  private resolvePersistence(env: NodeJS.ProcessEnv, consumerRoot: string): AppPersistenceConfig {
+    const url = env.CODEMATION_DATABASE_URL?.trim();
+    if (url) {
+      return this.databaseUrlParser.parse(url, consumerRoot);
     }
     return {
       kind: "sqlite",
-      databaseFilePath: this.resolveSqliteFilePath(database.sqliteFilePath, env, consumerRoot),
+      databaseFilePath: path.resolve(consumerRoot, ".codemation", "codemation.sqlite"),
     };
   }
 
-  private resolveDatabaseKind(
-    configuredKind: CodemationDatabaseKind | undefined,
-    databaseUrl: string | undefined,
-    env: NodeJS.ProcessEnv,
-  ): CodemationDatabaseKind {
-    const kindFromEnv = env.CODEMATION_DATABASE_KIND?.trim();
-    if (kindFromEnv === "postgresql" || kindFromEnv === "sqlite") {
-      return kindFromEnv;
-    }
-    if (configuredKind) {
-      return configuredKind;
-    }
-    const trimmedUrl = databaseUrl?.trim();
-    if (trimmedUrl && (trimmedUrl.startsWith("postgresql://") || trimmedUrl.startsWith("postgres://"))) {
-      return "postgresql";
-    }
-    return "sqlite";
-  }
-
-  private resolveSqliteFilePath(
-    configuredPath: string | undefined,
-    env: NodeJS.ProcessEnv,
-    consumerRoot: string,
-  ): string {
-    const envPath = env.CODEMATION_SQLITE_FILE_PATH?.trim();
-    if (envPath && envPath.length > 0) {
-      return path.isAbsolute(envPath) ? envPath : path.resolve(consumerRoot, envPath);
-    }
-    const trimmedConfiguredPath = configuredPath?.trim();
-    if (trimmedConfiguredPath && trimmedConfiguredPath.length > 0) {
-      return path.isAbsolute(trimmedConfiguredPath)
-        ? trimmedConfiguredPath
-        : path.resolve(consumerRoot, trimmedConfiguredPath);
-    }
-    return path.resolve(consumerRoot, ".codemation", "codemation.sqlite");
-  }
-
   private resolveSchedulerKind(
     runtimeConfig: CodemationApplicationRuntimeConfig,
     env: NodeJS.ProcessEnv,

package/src/bootstrap/runtime/FrontendRuntime.ts

@@ -41,8 +41,11 @@ export class FrontendRuntime {
   async start(args?: Readonly<{ skipPresentationServers?: boolean }>): Promise<void> {
     if (this.appConfig.env.CODEMATION_SKIP_STARTUP_MIGRATIONS !== "true") {
       await this.databaseMigrations.migrate();
-      await this.collectionSchemaSyncerHolder.syncIfAvailable();
     }
+    // Collection schema sync is gated separately: the CLI runs Prisma migrations ahead of dev startup
+    // and sets CODEMATION_SKIP_STARTUP_MIGRATIONS=true, but it cannot run consumer-defined collection
+    // sync because consumer collections are only known to the runtime via codemation.config.ts.
+    await this.collectionSchemaSyncerHolder.syncIfAvailable();
     await this.runtimeWorkflowActivationPolicy.hydrateFromRepository(this.workflowActivationRepository);
     if (args?.skipPresentationServers === true) {
       return;

package/src/bootstrap/runtime/WorkerRuntime.ts

@@ -45,12 +45,13 @@ export class WorkerRuntime {
   async start(queues: ReadonlyArray<string>): Promise<WorkerRuntimeHandle> {
     if (this.appConfig.env.CODEMATION_SKIP_STARTUP_MIGRATIONS !== "true") {
       await this.databaseMigrations.migrate();
-      await this.collectionSchemaSyncerHolder.syncIfAvailable();
     }
+    await this.collectionSchemaSyncerHolder.syncIfAvailable();
     await this.runtimeWorkflowActivationPolicy.hydrateFromRepository(this.workflowActivationRepository);
     const workflows = [...this.workflowRepository.list()];
     await this.engine.start(workflows);
     await this.runEventBusTelemetryReporter.start();
+    await this.lifecycle.startWorkerSubscribers();
     this.workflowRunRetentionPruneScheduler.start();
     const worker = this.scheduler.createWorker({
       queues,

package/src/credentials/BrokerClient.ts

@@ -0,0 +1,49 @@
+import { inject, injectable } from "@codemation/core";
+import { PairedFetch } from "../pairing/PairedFetch";
+import type { PairingConfig } from "../pairing/pairing.types";
+import { PairingConfigToken } from "../pairing/PairingConfigToken";
+import { BrokerRefreshInvalidGrantError } from "./BrokerRefreshInvalidGrantError";
+import { BrokerRefreshError } from "./BrokerRefreshError";
+
+export type BrokerRefreshResult = Readonly<{
+  accessToken: string;
+  expiresAt: number;
+  scopesGranted: ReadonlyArray<string>;
+  refreshToken?: string;
+}>;
+
+export { BrokerRefreshInvalidGrantError, BrokerRefreshError };
+
+/**
+ * Calls the control-plane broker's credential refresh endpoint via a HMAC-signed
+ * PairedFetch request. The broker performs the actual provider token exchange,
+ * keeping client_secret out of the installation.
+ *
+ * Endpoint: POST {controlPlaneUrl}/internal/credentials/refresh
+ */
+@injectable()
+export class BrokerClient {
+  constructor(
+    @inject(PairedFetch) private readonly pairedFetch: PairedFetch,
+    @inject(PairingConfigToken) private readonly pairingConfig: PairingConfig,
+  ) {}
+
+  async refreshCredential(
+    args: Readonly<{ credentialInstanceId: string; refreshToken: string }>,
+  ): Promise<BrokerRefreshResult> {
+    const url = `${this.pairingConfig.controlPlaneUrl}/internal/credentials/refresh`;
+    const response = await this.pairedFetch.post(url, {
+      credentialInstanceId: args.credentialInstanceId,
+      refreshToken: args.refreshToken,
+    });
+
+    if (response.status === 410) {
+      throw new BrokerRefreshInvalidGrantError(args.credentialInstanceId);
+    }
+    if (!response.ok) {
+      throw new BrokerRefreshError(args.credentialInstanceId, response.status);
+    }
+
+    return (await response.json()) as BrokerRefreshResult;
+  }
+}

package/src/credentials/BrokerRefreshError.ts

@@ -0,0 +1,12 @@
+/**
+ * Thrown when the broker returns an unexpected non-success HTTP status during refresh.
+ */
+export class BrokerRefreshError extends Error {
+  constructor(
+    readonly credentialInstanceId: string,
+    readonly status: number,
+  ) {
+    super(`Credential ${credentialInstanceId}: broker refresh failed with status ${status}.`);
+    this.name = "BrokerRefreshError";
+  }
+}

package/src/credentials/BrokerRefreshInvalidGrantError.ts

@@ -0,0 +1,13 @@
+/**
+ * Thrown when the control-plane broker returns HTTP 410 (invalid_grant).
+ * The refresh token is dead — user revoked, token rotated away, etc.
+ * The credential cannot be auto-recovered; the user must reconnect via the Connect flow.
+ */
+export class BrokerRefreshInvalidGrantError extends Error {
+  constructor(readonly credentialInstanceId: string) {
+    super(
+      `Credential ${credentialInstanceId}: refresh token is invalid or revoked (invalid_grant). Reconnect required.`,
+    );
+    this.name = "BrokerRefreshInvalidGrantError";
+  }
+}

package/src/credentials/ControlPlaneCatalogFetcher.ts

@@ -0,0 +1,261 @@
+import { inject, injectable } from "@codemation/core";
+import type { CredentialTypeDefinition, McpServerDeclaration } from "@codemation/core";
+import { ApplicationTokens } from "../applicationTokens";
+import type { LoggerFactory } from "../application/logging/Logger";
+import type { AppConfig } from "../presentation/config/AppConfig";
+import { PairedFetch } from "../pairing/PairedFetch";
+import { PairingConfigToken } from "../pairing/PairingConfigToken";
+import type { PairingConfig } from "../pairing/pairing.types";
+import type { OAuthAppCatalogEntry } from "./catalogTypes";
+
+/**
+ * Configuration read from env at construction time.
+ *
+ * - `CODEMATION_CATALOG_POLL_INTERVAL_SECONDS`: seconds between polls (default 300; 0 = startup-only).
+ * - `CODEMATION_CATALOG_STALE_FAILURES`: consecutive failures before warn → error escalation (default 5).
+ * - `CODEMATION_CATALOG_STALE_HOURS`: hours stale before escalating to error level (default 24).
+ */
+interface CatalogFetcherConfig {
+  readonly pollIntervalMs: number;
+  readonly staleFailuresThreshold: number;
+  readonly staleHoursThreshold: number;
+}
+
+type EndpointState = {
+  consecutiveFailures: number;
+  lastSuccessAt: Date | null;
+};
+
+/**
+ * Polls the three control-plane catalog endpoints on a configurable interval,
+ * caches the last-known-good responses, and exposes the fetched data for
+ * credential-type overrides, MCP server registrations, and OAuth app availability.
+ *
+ * Endpoints (HMAC-gated via PairedFetch):
+ *   GET /api/catalog/oauth-apps
+ *   GET /api/catalog/mcp-servers
+ *   GET /api/catalog/credential-types
+ *
+ * Failure semantics: a failure on one endpoint does NOT prevent updating the
+ * others. Each endpoint's consecutive-failure counter and staleness escalation
+ * are tracked independently.
+ *
+ * When not paired with a control plane (PairingConfigToken is null),
+ * start() returns immediately and all three getters remain null.
+ */
+@injectable()
+export class ControlPlaneCatalogFetcher {
+  private readonly config: CatalogFetcherConfig;
+  private timerHandle: ReturnType<typeof setTimeout> | null = null;
+  private stopped = false;
+  /** Tracks in-flight refresh so stop() can safely await it. */
+  private inFlight: Promise<void> | null = null;
+
+  private _oauthApps: readonly OAuthAppCatalogEntry[] | null = null;
+  private _mcpServers: readonly McpServerDeclaration[] | null = null;
+  private _credentialTypeOverrides: readonly CredentialTypeDefinition[] | null = null;
+
+  private readonly oauthAppsState: EndpointState = { consecutiveFailures: 0, lastSuccessAt: null };
+  private readonly mcpServersState: EndpointState = { consecutiveFailures: 0, lastSuccessAt: null };
+  private readonly credentialTypesState: EndpointState = { consecutiveFailures: 0, lastSuccessAt: null };
+
+  /**
+   * Called after each successful full fetch, before the next poll is scheduled.
+   * Set by AppContainerFactory to re-apply overrides on each refresh cycle.
+   */
+  onRefresh: (() => void) | null = null;
+
+  constructor(
+    @inject(PairedFetch) private readonly pairedFetch: PairedFetch,
+    @inject(PairingConfigToken, { isOptional: true }) private readonly pairingConfig: PairingConfig | null,
+    @inject(ApplicationTokens.LoggerFactory) private readonly loggers: LoggerFactory,
+    @inject(ApplicationTokens.AppConfig) appConfig: AppConfig,
+  ) {
+    const env = appConfig.env;
+    const pollSec = Number(env["CODEMATION_CATALOG_POLL_INTERVAL_SECONDS"] ?? 300);
+    const staleFailures = Number(env["CODEMATION_CATALOG_STALE_FAILURES"] ?? 5);
+    const staleHours = Number(env["CODEMATION_CATALOG_STALE_HOURS"] ?? 24);
+    this.config = {
+      pollIntervalMs: Number.isFinite(pollSec) ? pollSec * 1_000 : 300_000,
+      staleFailuresThreshold: Number.isFinite(staleFailures) ? staleFailures : 5,
+      staleHoursThreshold: Number.isFinite(staleHours) ? staleHours : 24,
+    };
+  }
+
+  /** Latest fetched OAuth app catalog; null until first successful fetch. */
+  get oauthApps(): readonly OAuthAppCatalogEntry[] | null {
+    return this._oauthApps;
+  }
+
+  /** Latest fetched MCP server declarations; null until first successful fetch. */
+  get mcpServers(): readonly McpServerDeclaration[] | null {
+    return this._mcpServers;
+  }
+
+  /** Latest fetched credential type overrides; null until first successful fetch. */
+  get credentialTypeOverrides(): readonly CredentialTypeDefinition[] | null {
+    return this._credentialTypeOverrides;
+  }
+
+  /**
+   * Fires the first fetch (non-blocking — failure is logged, not thrown) and
+   * schedules the periodic poll if `pollIntervalMs > 0`.
+   * No-ops immediately when pairing config is absent.
+   */
+  async start(): Promise<void> {
+    if (!this.pairingConfig) {
+      return;
+    }
+    try {
+      await this.refresh();
+    } catch {
+      // refresh() handles its own errors; this catch is belt-and-suspenders.
+    }
+    this.scheduleNext();
+  }
+
+  /**
+   * Cancels the poll timer. Awaits any in-flight fetch before resolving.
+   */
+  async stop(): Promise<void> {
+    this.stopped = true;
+    if (this.timerHandle !== null) {
+      clearTimeout(this.timerHandle);
+      this.timerHandle = null;
+    }
+    if (this.inFlight) {
+      await this.inFlight;
+    }
+  }
+
+  /**
+   * Manual one-shot fetch. Same code path as the periodic tick.
+   * Errors are caught and logged internally; this method never rejects.
+   */
+  async refresh(): Promise<void> {
+    const run = this.fetchAll();
+    this.inFlight = run;
+    try {
+      await run;
+    } finally {
+      if (this.inFlight === run) {
+        this.inFlight = null;
+      }
+    }
+  }
+
+  private scheduleNext(): void {
+    if (this.stopped || this.config.pollIntervalMs <= 0) {
+      return;
+    }
+    this.timerHandle = setTimeout(() => {
+      if (this.stopped) {
+        return;
+      }
+      void this.refresh().finally(() => this.scheduleNext());
+    }, this.config.pollIntervalMs);
+  }
+
+  private async fetchAll(): Promise<void> {
+    if (!this.pairingConfig) {
+      return;
+    }
+    const logger = this.loggers.create("ControlPlaneCatalogFetcher");
+    const base = this.pairingConfig.controlPlaneUrl;
+
+    const [oauthResult, mcpResult, credTypesResult] = await Promise.allSettled([
+      this.pairedFetch.get(`${base}/api/catalog/oauth-apps`),
+      this.pairedFetch.get(`${base}/api/catalog/mcp-servers`),
+      this.pairedFetch.get(`${base}/api/catalog/credential-types`),
+    ]);
+
+    await this.handleEndpointResult(
+      oauthResult,
+      this.oauthAppsState,
+      "oauth-apps",
+      (data) => {
+        this._oauthApps = data as OAuthAppCatalogEntry[];
+      },
+      logger,
+    );
+
+    await this.handleEndpointResult(
+      mcpResult,
+      this.mcpServersState,
+      "mcp-servers",
+      (data) => {
+        this._mcpServers = data as McpServerDeclaration[];
+      },
+      logger,
+    );
+
+    await this.handleEndpointResult(
+      credTypesResult,
+      this.credentialTypesState,
+      "credential-types",
+      (data) => {
+        this._credentialTypeOverrides = data as CredentialTypeDefinition[];
+      },
+      logger,
+    );
+
+    this.onRefresh?.();
+  }
+
+  private async handleEndpointResult(
+    result: PromiseSettledResult<Response>,
+    state: EndpointState,
+    endpointName: string,
+    onSuccess: (data: unknown[]) => void,
+    logger: ReturnType<LoggerFactory["create"]>,
+  ): Promise<void> {
+    if (result.status === "fulfilled") {
+      const res = result.value;
+      if (res.ok) {
+        try {
+          const data = (await res.json()) as unknown[];
+          onSuccess(data);
+          state.consecutiveFailures = 0;
+          state.lastSuccessAt = new Date();
+          logger.info(`ControlPlaneCatalogFetcher: fetched ${endpointName} (count=${data.length})`);
+          return;
+        } catch (err) {
+          this.logEndpointFailure(state, endpointName, err, logger);
+          return;
+        }
+      }
+      this.logEndpointFailure(state, endpointName, new Error(`HTTP ${res.status} ${res.statusText}`), logger);
+    } else {
+      this.logEndpointFailure(state, endpointName, result.reason, logger);
+    }
+  }
+
+  private logEndpointFailure(
+    state: EndpointState,
+    endpointName: string,
+    err: unknown,
+    logger: ReturnType<LoggerFactory["create"]>,
+  ): void {
+    state.consecutiveFailures++;
+    const staleHours = state.lastSuccessAt ? (Date.now() - state.lastSuccessAt.getTime()) / 3_600_000 : null;
+    const errMsg = err instanceof Error ? err.message : String(err);
+
+    const isStale =
+      state.consecutiveFailures >= this.config.staleFailuresThreshold ||
+      (staleHours !== null && staleHours >= this.config.staleHoursThreshold);
+
+    if (isStale) {
+      const staleLabel = staleHours !== null ? `${staleHours.toFixed(1)}h` : "never-succeeded";
+      logger.error(
+        `ControlPlaneCatalogFetcher: ${endpointName} is stale — control plane unreachable (failures=${state.consecutiveFailures}, stale=${staleLabel}): ${errMsg}`,
+        err instanceof Error ? err : undefined,
+      );
+    } else {
+      logger.warn(
+        `ControlPlaneCatalogFetcher: ${endpointName} fetch failed, retaining prior cached value (failures=${state.consecutiveFailures}): ${errMsg}`,
+        err instanceof Error ? err : undefined,
+      );
+    }
+    // NOTE: cached value is intentionally preserved (last-known-good).
+  }
+}