@codemation/host 0.6.0 → 0.8.0

package/src/presentation/frontend/PublicFrontendBootstrapJsonCodec.ts

@@ -15,7 +15,7 @@ export class PublicFrontendBootstrapJsonCodec {
       if (!parsed || typeof parsed !== "object") {
         return null;
       }
-      return {
+      const base: PublicFrontendBootstrap = {
         credentialsEnabled: parsed.credentialsEnabled === true,
         logoUrl: typeof parsed.logoUrl === "string" && parsed.logoUrl.trim().length > 0 ? parsed.logoUrl : null,
         oauthProviders: this.resolveOauthProviders(parsed.oauthProviders),
@@ -25,6 +25,9 @@ export class PublicFrontendBootstrapJsonCodec {
             : "Codemation",
         uiAuthEnabled: parsed.uiAuthEnabled !== false,
       };
+      const cpWebOrigin =
+        typeof parsed.cpWebOrigin === "string" && parsed.cpWebOrigin.trim().length > 0 ? parsed.cpWebOrigin : undefined;
+      return cpWebOrigin ? { ...base, cpWebOrigin } : base;
     } catch {
       return null;
     }

package/src/presentation/http/ApiPaths.ts

@@ -145,10 +145,6 @@ export class ApiPaths {
     return `${this.apiBasePath}/credential-bindings`;
   }
 
-  static oauth2Auth(instanceId: string): string {
-    return `${this.oauth2BasePath}/auth?instanceId=${encodeURIComponent(instanceId)}`;
-  }
-
   static oauth2RedirectUri(): string {
     return `${this.oauth2BasePath}/redirect-uri`;
   }
@@ -157,6 +153,10 @@ export class ApiPaths {
     return `${this.oauth2BasePath}/disconnect?instanceId=${encodeURIComponent(instanceId)}`;
   }
 
+  static credentialOAuthStart(): string {
+    return `${this.credentialsBasePath}/oauth/start`;
+  }
+
   static workflowWebsocket(): string {
     return `${this.workflowsBasePath}/ws`;
   }

package/src/presentation/http/HeadlessHttpServerFactory.ts

@@ -0,0 +1,56 @@
+import { createServer, type Server } from "node:http";
+import type { Logger } from "../../application/logging/Logger";
+import type { CodemationHonoApiApp } from "./hono/CodemationHonoApiAppFactory";
+
+/**
+ * Creates a Node.js http.Server that bridges IncomingMessage to Hono's Fetch API.
+ * Used by {@link import("../../bootstrap/runtime/HeadlessApiRuntime").HeadlessApiRuntime}
+ * to serve the Hono API without Next.js.
+ */
+export class HeadlessHttpServerFactory {
+  create(honoApp: CodemationHonoApiApp, port: number, logger: Logger): Server {
+    return createServer((req, res) => {
+      const url = new URL(req.url ?? "/", `http://${req.headers.host ?? `127.0.0.1:${port}`}`);
+      const headers = new Headers();
+      for (const [key, value] of Object.entries(req.headers)) {
+        if (value === undefined) continue;
+        if (Array.isArray(value)) {
+          for (const v of value) headers.append(key, v);
+        } else {
+          headers.set(key, value);
+        }
+      }
+      const chunks: Buffer[] = [];
+      req.on("data", (chunk: Buffer) => chunks.push(chunk));
+      req.on("end", () => {
+        // eslint-disable-next-line codemation/no-buffer-everything -- node:http bridge; no streaming alternative when adapting IncomingMessage to Fetch API Request
+        const body = chunks.length > 0 ? Buffer.concat(chunks) : null;
+        const fetchRequest = new Request(url, {
+          method: req.method ?? "GET",
+          headers,
+          body: body?.byteLength ? body : undefined,
+          // @ts-expect-error — Node's Request needs duplex for streaming; required in some runtimes
+          duplex: "half",
+        });
+        Promise.resolve(honoApp.fetch(fetchRequest))
+          .then(async (fetchResponse: Response) => {
+            const responseHeaders: Record<string, string> = {};
+            fetchResponse.headers.forEach((value, key) => {
+              responseHeaders[key] = value;
+            });
+            res.writeHead(fetchResponse.status, responseHeaders);
+            // eslint-disable-next-line codemation/no-buffer-everything -- node:http bridge; Hono Fetch Response must be fully buffered to write to ServerResponse
+            const responseBody = await fetchResponse.arrayBuffer();
+            res.end(Buffer.from(responseBody));
+          })
+          .catch((err: unknown) => {
+            logger.error("Unhandled request error", err instanceof Error ? err : new Error(String(err)));
+            if (!res.headersSent) {
+              res.writeHead(500);
+              res.end("Internal server error");
+            }
+          });
+      });
+    });
+  }
+}

package/src/presentation/http/ServerHttpErrorResponseFactory.ts

@@ -1,13 +1,50 @@
 import { ApplicationRequestError } from "../../application/ApplicationRequestError";
 
+/**
+ * Shape of the JSON body returned on an unhandled 500. The canvas (and any other client)
+ * reads `message` + optional `stack` + optional `cause` to surface a copy/pastable error
+ * dialog. Generic "Internal server error" with no detail makes operator triage impossible
+ * — this contract preserves the diagnostic information the CLI logs anyway.
+ */
+export type ServerHttpUnhandledErrorPayload = Readonly<{
+  error: "Internal server error";
+  message: string;
+  name?: string;
+  stack?: string;
+  cause?: string;
+}>;
+
 export class ServerHttpErrorResponseFactory {
   static fromUnknown(error: unknown): Response {
     if (error instanceof ApplicationRequestError) {
       return Response.json(error.payload, { status: error.status });
     }
     this.logUnexpectedError(error);
-    const message = error instanceof Error ? error.message : String(error);
-    return Response.json({ error: message }, { status: 500 });
+    return Response.json(this.toUnhandledPayload(error), { status: 500 });
+  }
+
+  private static toUnhandledPayload(error: unknown): ServerHttpUnhandledErrorPayload {
+    if (error instanceof Error) {
+      return {
+        error: "Internal server error",
+        message: error.message || `${error.name}: <no message>`,
+        name: error.name,
+        stack: error.stack,
+        cause: this.formatCauseValue(error),
+      };
+    }
+    return { error: "Internal server error", message: String(error) };
+  }
+
+  private static formatCauseValue(error: Error): string | undefined {
+    if (!("cause" in error) || !error.cause) {
+      return undefined;
+    }
+    const cause = error.cause;
+    if (cause instanceof Error) {
+      return cause.stack ?? `${cause.name}: ${cause.message}`;
+    }
+    return String(cause);
   }
 
   private static logUnexpectedError(error: unknown): void {

package/src/presentation/http/hono/CodemationHonoApiAppFactory.ts

@@ -5,7 +5,9 @@ import { ApplicationTokens } from "../../../applicationTokens";
 import { BinaryHttpRouteHandler } from "../routeHandlers/BinaryHttpRouteHandlerFactory";
 import { ServerHttpErrorResponseFactory } from "../ServerHttpErrorResponseFactory";
 import type { HonoApiRouteRegistrar } from "./HonoApiRouteRegistrar";
+import type { InternalHonoApiRouteRegistrar } from "./InternalHonoApiRouteRegistrar";
 import { HonoHttpAnonymousRoutePolicy } from "./HonoHttpAnonymousRoutePolicyRegistry";
+import { ManagedCorsMiddleware } from "../../../auth/managed/ManagedCorsMiddleware";
 
 @injectable()
 export class CodemationHonoApiApp {
@@ -18,10 +20,21 @@ export class CodemationHonoApiApp {
     registrars: ReadonlyArray<HonoApiRouteRegistrar>,
     @inject(BinaryHttpRouteHandler)
     binaryHttpRouteHandler: BinaryHttpRouteHandler,
+    @injectAll(ApplicationTokens.InternalHonoApiRouteRegistrar, { isOptional: true })
+    internalRegistrars: ReadonlyArray<InternalHonoApiRouteRegistrar>,
+    @injectAll(ApplicationTokens.ManagedCorsMiddleware, { isOptional: true })
+    corsMiddlewareList: ReadonlyArray<ManagedCorsMiddleware>,
   ) {
-    const app = new Hono().basePath("/api");
-    app.onError((error, _c) => ServerHttpErrorResponseFactory.fromUnknown(error));
-    app.use("*", async (c, next) => {
+    // Root app — composes /api/* (auth-gated) and /internal/* (HMAC-gated) sub-apps.
+    const root = new Hono();
+    const corsMiddleware = corsMiddlewareList[0] ?? null;
+    if (corsMiddleware) {
+      root.use("*", corsMiddleware.handle());
+    }
+
+    const api = new Hono().basePath("/api");
+    api.onError((error, _c) => ServerHttpErrorResponseFactory.fromUnknown(error));
+    api.use("*", async (c, next) => {
       if (HonoHttpAnonymousRoutePolicy.isAnonymousRoute(c.req.raw)) {
         await next();
         return;
@@ -33,25 +46,37 @@ export class CodemationHonoApiApp {
       await next();
     });
     for (const registrar of registrars) {
-      registrar.register(app);
+      registrar.register(api);
     }
-    app.get("/workflows/:workflowId/debugger-overlay/binary/:binaryId/content", (c) =>
+    api.get("/workflows/:workflowId/debugger-overlay/binary/:binaryId/content", (c) =>
       binaryHttpRouteHandler.getWorkflowOverlayBinaryContent(c.req.raw, {
         workflowId: c.req.param("workflowId"),
         binaryId: c.req.param("binaryId"),
       }),
     );
-    app.post("/workflows/:workflowId/debugger-overlay/binary/upload", (c) =>
+    api.post("/workflows/:workflowId/debugger-overlay/binary/upload", (c) =>
       binaryHttpRouteHandler.postWorkflowDebuggerOverlayBinaryUpload(c.req.raw, {
         workflowId: c.req.param("workflowId"),
       }),
     );
-    app.notFound((c) => {
+    api.notFound((c) => {
       const method = c.req.method.toUpperCase();
       const url = new URL(c.req.url);
       return c.json({ error: `Unknown API route: ${method} ${url.pathname}` }, 404);
     });
-    this.app = app;
+
+    root.route("/", api);
+
+    // /internal/* routes — only mounted when pairing is configured.
+    if (internalRegistrars.length > 0) {
+      const internal = new Hono();
+      for (const registrar of internalRegistrars) {
+        registrar.register(internal);
+      }
+      root.route("/", internal);
+    }
+
+    this.app = root;
   }
 
   getHono(): Hono {

package/src/presentation/http/hono/InternalHonoApiRouteRegistrar.ts

@@ -0,0 +1,12 @@
+import type { Hono } from "hono";
+
+/**
+ * Registrar interface for routes mounted on the installation's internal Hono app
+ * (no `/api` prefix). All routes registered here are accessible at `/internal/<path>`
+ * and are protected by HMAC auth middleware.
+ *
+ * See docs/pairing-protocol.md for the wire format and auth requirements.
+ */
+export interface InternalHonoApiRouteRegistrar {
+  register(app: Hono): void;
+}

package/src/presentation/http/hono/registrars/ManagedMeHonoApiRouteRegistrar.ts

@@ -0,0 +1,35 @@
+import { inject, injectable } from "@codemation/core";
+import { Hono } from "hono";
+import type { HonoApiRouteRegistrar } from "../HonoApiRouteRegistrar";
+import type { SessionVerifier } from "../../../../application/auth/SessionVerifier";
+import { ApplicationTokens } from "../../../../applicationTokens";
+
+/**
+ * Exposes `GET /api/me` in managed-auth mode.
+ *
+ * Reads the JWT principal by re-verifying the Bearer token, and returns
+ * `{ userId, workspaceId }`. No DB lookup needed — the JWT is the source of truth.
+ *
+ * Only registered when `auth.kind === "managed"`.
+ */
+@injectable()
+export class ManagedMeHonoApiRouteRegistrar implements HonoApiRouteRegistrar {
+  constructor(
+    @inject(ApplicationTokens.SessionVerifier)
+    private readonly sessionVerifier: SessionVerifier,
+  ) {}
+
+  register(app: Hono): void {
+    app.get("/me", async (c) => {
+      try {
+        const principal = await this.sessionVerifier.verify(c.req.raw);
+        if (!principal) {
+          return c.json({ error: "Unauthorized" }, 401);
+        }
+        return c.json({ userId: principal.id, workspaceId: principal.workspaceId ?? null });
+      } catch {
+        return c.json({ error: "Unauthorized" }, 401);
+      }
+    });
+  }
+}

package/src/presentation/http/hono/registrars/OAuth2HonoApiRouteRegistrar.ts

@@ -8,8 +8,8 @@ export class OAuth2HonoApiRouteRegistrar implements HonoApiRouteRegistrar {
   constructor(@inject(OAuth2HttpRouteHandler) private readonly handler: OAuth2HttpRouteHandler) {}
 
   register(app: Hono): void {
-    app.get("/oauth2/auth", (c) => this.handler.getAuthRedirect(c.req.raw));
-    app.get("/oauth2/callback", (c) => this.handler.getCallback(c.req.raw));
+    app.post("/credentials/oauth/start", (c) => this.handler.postOAuthStart(c.req.raw));
+    app.get("/oauth2/callback", (c) => this.handler.getOAuthCallback(c.req.raw));
     app.get("/oauth2/redirect-uri", (c) => this.handler.getRedirectUri(c.req.raw));
     app.post("/oauth2/disconnect", (c) => this.handler.postDisconnect(c.req.raw));
   }

package/src/presentation/http/routeHandlers/CredentialHttpRouteHandler.ts

@@ -2,6 +2,7 @@ import { inject, injectable } from "@codemation/core";
 import { HttpRequestJsonBodyReader } from "../HttpRequestJsonBodyReader";
 import type { CommandBus } from "../../../application/bus/CommandBus";
 import type { QueryBus } from "../../../application/bus/QueryBus";
+import type { SessionVerifier } from "../../../application/auth/SessionVerifier";
 import {
   CreateCredentialInstanceCommand,
   DeleteCredentialInstanceCommand,
@@ -23,6 +24,8 @@ import {
   ListCredentialTypesQuery,
 } from "../../../application/queries/CredentialQueryHandlers";
 import { ApplicationTokens } from "../../../applicationTokens";
+import type { PairingConfig } from "../../../pairing/pairing.types";
+import { PairingConfigToken } from "../../../pairing/PairingConfigToken";
 import { ServerHttpErrorResponseFactory } from "../ServerHttpErrorResponseFactory";
 import type { ServerHttpRouteParams } from "../ServerHttpRouteParams";
 
@@ -33,6 +36,10 @@ export class CredentialHttpRouteHandler {
     private readonly queryBus: QueryBus,
     @inject(ApplicationTokens.CommandBus)
     private readonly commandBus: CommandBus,
+    @inject(ApplicationTokens.SessionVerifier)
+    private readonly sessionVerifier: SessionVerifier,
+    @inject(PairingConfigToken, { isOptional: true })
+    private readonly pairingConfig: PairingConfig | null,
   ) {}
 
   async getCredentialTypes(): Promise<Response> {
@@ -62,6 +69,27 @@ export class CredentialHttpRouteHandler {
   async getCredentialInstance(request: Request, params: ServerHttpRouteParams): Promise<Response> {
     try {
       const withSecrets = new URL(request.url).searchParams.get("withSecrets") === "1";
+
+      if (withSecrets) {
+        // Ownership check: fail-closed.
+        // - If the session verifier returns null (unauthenticated), reject.
+        // - In managed-JWT mode the principal's workspaceId must match the
+        //   installation's own workspaceId (from PairingConfig).
+        // - In local-auth mode (pairingConfig absent) a valid non-null principal
+        //   is sufficient — no cross-workspace check is possible or needed.
+        const principal = await this.sessionVerifier.verify(request);
+        if (!principal) {
+          return Response.json({ error: "Forbidden" }, { status: 403 });
+        }
+        if (
+          principal.source === "managed-jwt" &&
+          this.pairingConfig !== null &&
+          principal.workspaceId !== this.pairingConfig.workspaceId
+        ) {
+          return Response.json({ error: "Forbidden" }, { status: 403 });
+        }
+      }
+
       const instance = withSecrets
         ? await this.queryBus.execute(new GetCredentialInstanceWithSecretsQuery(params.instanceId!))
         : await this.queryBus.execute(new GetCredentialInstanceQuery(params.instanceId!));

package/src/presentation/http/routeHandlers/OAuth2HttpRouteHandlerFactory.ts

@@ -1,79 +1,136 @@
+import type { OAuthFlowExecutor } from "@codemation/core";
 import { inject, injectable } from "@codemation/core";
 import serialize from "serialize-javascript";
-import { CredentialInstanceService } from "../../../domain/credentials/CredentialServices";
-import { OAuth2ConnectService } from "../../../domain/credentials/OAuth2ConnectServiceFactory";
+import { ApplicationTokens } from "../../../applicationTokens";
+import {
+  CredentialInstanceService,
+  CredentialSecretCipher,
+  type CredentialStore,
+} from "../../../domain/credentials/CredentialServices";
+import { OAuth2RedirectUriResolver } from "../../../domain/credentials/OAuth2RedirectUriResolver";
+import { HttpRequestJsonBodyReader } from "../HttpRequestJsonBodyReader";
 import { ServerHttpErrorResponseFactory } from "../ServerHttpErrorResponseFactory";
 
+type OAuthStartRequestBody = Readonly<{
+  typeId: string;
+  instanceId: string;
+  redirectUri: string;
+  scopes?: ReadonlyArray<string>;
+}>;
+
 @injectable()
 export class OAuth2HttpRouteHandler {
   constructor(
-    @inject(OAuth2ConnectService)
-    private readonly oauth2ConnectService: OAuth2ConnectService,
+    @inject(OAuth2RedirectUriResolver)
+    private readonly redirectUriResolver: OAuth2RedirectUriResolver,
     @inject(CredentialInstanceService)
     private readonly credentialInstanceService: CredentialInstanceService,
+    @inject(ApplicationTokens.OAuthFlowExecutor)
+    private readonly oauthFlowExecutor: OAuthFlowExecutor,
+    @inject(ApplicationTokens.CredentialStore)
+    private readonly credentialStore: CredentialStore,
+    @inject(CredentialSecretCipher)
+    private readonly credentialSecretCipher: CredentialSecretCipher,
   ) {}
 
-  async getAuthRedirect(request: Request): Promise<Response> {
+  async getRedirectUri(request: Request): Promise<Response> {
     try {
-      const url = new URL(request.url);
-      const instanceId = url.searchParams.get("instanceId")?.trim();
-      if (!instanceId) {
-        return Response.json({ error: "Missing instanceId query parameter." }, { status: 400 });
-      }
-      const redirect = await this.oauth2ConnectService.createAuthRedirect(
-        instanceId,
-        this.resolveRequestOrigin(request),
-      );
-      return Response.redirect(redirect.redirectUrl, 302);
+      return Response.json({
+        redirectUri: this.redirectUriResolver.resolve(this.resolveRequestOrigin(request)),
+      });
     } catch (error) {
       return ServerHttpErrorResponseFactory.fromUnknown(error);
     }
   }
 
-  async getCallback(request: Request): Promise<Response> {
+  async postDisconnect(request: Request): Promise<Response> {
     try {
       const url = new URL(request.url);
-      const result = await this.oauth2ConnectService.handleCallback({
-        code: url.searchParams.get("code"),
-        state: url.searchParams.get("state"),
-        requestOrigin: this.resolveRequestOrigin(request),
-      });
-      return new Response(this.createPopupHtml({ kind: "oauth2.connected", ...result }), {
-        headers: {
-          "content-type": "text/html; charset=utf-8",
-        },
-      });
+      const instanceId = url.searchParams.get("instanceId")?.trim();
+      if (!instanceId) {
+        return Response.json({ error: "Missing instanceId query parameter." }, { status: 400 });
+      }
+      return Response.json(await this.credentialInstanceService.disconnectOAuth2(instanceId));
     } catch (error) {
-      const message = error instanceof Error ? error.message : String(error);
-      return new Response(this.createPopupHtml({ kind: "oauth2.error", message }), {
-        status: 400,
-        headers: {
-          "content-type": "text/html; charset=utf-8",
-        },
-      });
+      return ServerHttpErrorResponseFactory.fromUnknown(error);
     }
   }
 
-  async getRedirectUri(request: Request): Promise<Response> {
+  async postOAuthStart(request: Request): Promise<Response> {
     try {
-      return Response.json({
-        redirectUri: this.oauth2ConnectService.getRedirectUri(this.resolveRequestOrigin(request)),
+      const body = await HttpRequestJsonBodyReader.readJsonBody<OAuthStartRequestBody>(request);
+      if (!body.typeId?.trim()) {
+        return Response.json({ error: "Missing required field: typeId" }, { status: 400 });
+      }
+      if (!body.instanceId?.trim()) {
+        return Response.json({ error: "Missing required field: instanceId" }, { status: 400 });
+      }
+      if (!body.redirectUri?.trim()) {
+        return Response.json({ error: "Missing required field: redirectUri" }, { status: 400 });
+      }
+      const result = await this.oauthFlowExecutor.start({
+        typeId: body.typeId.trim(),
+        instanceId: body.instanceId.trim(),
+        redirectUri: body.redirectUri.trim(),
+        scopes: body.scopes ?? [],
       });
+      return Response.json({ consentUrl: result.consentUrl, stateToken: result.stateToken });
     } catch (error) {
       return ServerHttpErrorResponseFactory.fromUnknown(error);
     }
   }
 
-  async postDisconnect(request: Request): Promise<Response> {
+  async getOAuthCallback(request: Request): Promise<Response> {
     try {
       const url = new URL(request.url);
-      const instanceId = url.searchParams.get("instanceId")?.trim();
+      const code = url.searchParams.get("code")?.trim();
+      const stateToken = url.searchParams.get("state")?.trim();
+      if (!code || !stateToken) {
+        return new Response(
+          this.createPopupHtml({ kind: "oauth2.error", message: "Missing code or state parameter." }),
+          {
+            status: 400,
+            headers: { "content-type": "text/html; charset=utf-8" },
+          },
+        );
+      }
+      const instanceId = this.oauthFlowExecutor.lookupInstanceId(stateToken);
       if (!instanceId) {
-        return Response.json({ error: "Missing instanceId query parameter." }, { status: 400 });
+        return new Response(
+          this.createPopupHtml({ kind: "oauth2.error", message: "OAuth state token not found or already used." }),
+          { status: 400, headers: { "content-type": "text/html; charset=utf-8" } },
+        );
       }
-      return Response.json(await this.credentialInstanceService.disconnectOAuth2(instanceId));
+      const material = await this.oauthFlowExecutor.completeCallback({ stateToken, code });
+      const nowIso = new Date().toISOString();
+      const encryptedMaterial = this.credentialSecretCipher.encrypt({
+        accessToken: material.accessToken,
+        refreshToken: material.refreshToken ?? null,
+        expiresAt: material.expiresAt ?? null,
+        grantedScopes: material.grantedScopes.join(" "),
+      });
+      await this.credentialStore.saveOAuth2Material({
+        instanceId,
+        encryptedJson: encryptedMaterial.encryptedJson,
+        encryptionKeyId: encryptedMaterial.encryptionKeyId,
+        schemaVersion: encryptedMaterial.schemaVersion,
+        metadata: {
+          providerId: "local",
+          connectedAt: nowIso,
+          scopes: [...material.grantedScopes],
+          updatedAt: nowIso,
+        },
+      });
+      await this.credentialInstanceService.markOAuth2Connected(instanceId, nowIso);
+      return new Response(this.createPopupHtml({ kind: "oauth2.connected", instanceId }), {
+        headers: { "content-type": "text/html; charset=utf-8" },
+      });
     } catch (error) {
-      return ServerHttpErrorResponseFactory.fromUnknown(error);
+      const message = error instanceof Error ? error.message : String(error);
+      return new Response(this.createPopupHtml({ kind: "oauth2.error", message }), {
+        status: 400,
+        headers: { "content-type": "text/html; charset=utf-8" },
+      });
     }
   }
 

package/src/presentation/server/CodemationConsumerConfigLoader.ts

@@ -6,6 +6,7 @@ import type { NamespacedUnregister } from "tsx/esm/api";
 import type { CodemationConfig } from "../config/CodemationConfig";
 import { CodemationConfigNormalizer } from "../config/CodemationConfigNormalizer";
 import type { NormalizedCodemationConfig } from "../config/CodemationConfigNormalizer";
+import { BootTimer } from "../../bootstrap/perf/BootTimer";
 import { logLevelPolicyFactory } from "../../infrastructure/logging/LogLevelPolicyFactory";
 import { ServerLoggerFactory } from "../../infrastructure/logging/ServerLoggerFactory";
 import { DiscoveredWorkflowsEmptyMessageFactory } from "./DiscoveredWorkflowsEmptyMessageFactory";
@@ -37,9 +38,46 @@ export class CodemationConsumerConfigLoader {
   private readonly performanceDiagnosticsLogger = new ServerLoggerFactory(
     logLevelPolicyFactory,
   ).createPerformanceDiagnostics("codemation-config-loader.timing");
+  private readonly bootLogger = new ServerLoggerFactory(logLevelPolicyFactory).create("codemation.boot");
+  /**
+   * In-flight + completed load promises keyed by `${consumerRoot}|${configPathOverride}`. The
+   * boot path constructs MULTIPLE CodemationConsumerConfigLoader instances (one inside the CLI's
+   * DatabaseMigrationsApplyService, another inside NextHostEdgeSeedLoader, another inside
+   * AppConfigLoader for the disposable runtime) and each independently calls `load(...)`. Without
+   * a cache shared across instances, the same `${consumerRoot}` ends up importing
+   * codemation.config.ts + discovered workflow modules ~3 times for a single dev boot. The cache
+   * has to be static so it spans every loader instance in the process.
+   *
+   * Callers MUST invoke `invalidateAll()` on a source-change reload — the dev source watcher
+   * already tears the runtime down and reboots; it just needs to clear this map first.
+   */
+  private static readonly resolutionCache = new Map<string, Promise<CodemationConsumerConfigResolution>>();
+
+  static invalidateAll(): void {
+    this.resolutionCache.clear();
+  }
 
   async load(
     args: Readonly<{ consumerRoot: string; configPathOverride?: string }>,
+  ): Promise<CodemationConsumerConfigResolution> {
+    const cacheKey = `${args.consumerRoot}|${args.configPathOverride ?? ""}`;
+    const cached = CodemationConsumerConfigLoader.resolutionCache.get(cacheKey);
+    if (cached) {
+      return cached;
+    }
+    const promise = this.loadUncached(args);
+    CodemationConsumerConfigLoader.resolutionCache.set(cacheKey, promise);
+    try {
+      return await promise;
+    } catch (error) {
+      // A failed load shouldn't poison the cache — future retries should re-attempt.
+      CodemationConsumerConfigLoader.resolutionCache.delete(cacheKey);
+      throw error;
+    }
+  }
+
+  private async loadUncached(
+    args: Readonly<{ consumerRoot: string; configPathOverride?: string }>,
   ): Promise<CodemationConsumerConfigResolution> {
     const loadStarted = performance.now();
     let mark = loadStarted;
@@ -54,25 +92,36 @@ export class CodemationConsumerConfigLoader {
         `load.${label} +${delta.toFixed(1)}ms (cumulative ${(now - loadStarted).toFixed(1)}ms)`,
       );
     };
-    const bootstrapSource = await this.resolveConfigPath(args.consumerRoot, args.configPathOverride);
+    const bootstrapSource = await BootTimer.measureAsync("config.resolveConfigPath", () =>
+      this.resolveConfigPath(args.consumerRoot, args.configPathOverride),
+    );
     phaseMs("resolveConfigPath");
     if (!bootstrapSource) {
       throw new Error(
         'Codemation config not found. Expected "codemation.config.ts" in the consumer project root or "src/".',
       );
     }
-    const moduleExports = await this.importModule(bootstrapSource, importSession);
+    const moduleExports = await BootTimer.measureAsync("config.importConfigModule", () =>
+      this.importModule(bootstrapSource, importSession),
+    );
     phaseMs("importConfigModule");
     const rawConfig = this.configExportsResolver.resolveConfig(moduleExports);
     if (!rawConfig) {
       throw new Error(`Config file does not export a Codemation config object: ${bootstrapSource}`);
     }
     const config = this.configNormalizer.normalize(rawConfig);
-    const workflowSources = await this.resolveWorkflowSources(args.consumerRoot, config);
+    if (rawConfig.codemationVersion) {
+      this.bootLogger.info(`codemationVersion: ${rawConfig.codemationVersion}`);
+    }
+    const workflowSources = await BootTimer.measureAsync("config.resolveWorkflowSources", () =>
+      this.resolveWorkflowSources(args.consumerRoot, config),
+    );
     phaseMs("resolveWorkflowSources");
-    const workflows = this.mergeWorkflows(
-      config.workflows ?? [],
-      await this.loadDiscoveredWorkflows(args.consumerRoot, config, workflowSources, importSession),
+    const workflows = await BootTimer.measureAsync("config.loadDiscoveredWorkflows", async () =>
+      this.mergeWorkflows(
+        config.workflows ?? [],
+        await this.loadDiscoveredWorkflows(args.consumerRoot, config, workflowSources, importSession),
+      ),
     );
     phaseMs("loadDiscoveredWorkflows");
     const resolvedConfig: NormalizedCodemationConfig = {
@@ -145,7 +194,10 @@ export class CodemationConsumerConfigLoader {
           workflowDiscoveryDirectories,
           absoluteWorkflowModulePath: workflowSource,
         }),
-        moduleExports: await this.importModule(workflowSource, importSession),
+        moduleExports: await BootTimer.measureAsync(
+          `workflow.${path.basename(workflowSource).replace(/\.tsx?$/, "")}`,
+          () => this.importModule(workflowSource, importSession),
+        ),
       })),
     );
     for (const loadedWorkflowModule of loadedWorkflowModules) {

package/src/presentation/server/CodemationPluginDiscovery.ts

@@ -124,6 +124,7 @@ export class CodemationPluginDiscovery {
     }
     const pluginValue = value as {
       credentialTypes?: unknown;
+      mcpServers?: unknown;
       register?: unknown;
       sandbox?: unknown;
     };
@@ -133,9 +134,13 @@ export class CodemationPluginDiscovery {
     if (pluginValue.credentialTypes !== undefined && !Array.isArray(pluginValue.credentialTypes)) {
       return false;
     }
+    if (pluginValue.mcpServers !== undefined && !Array.isArray(pluginValue.mcpServers)) {
+      return false;
+    }
     return (
       pluginValue.register !== undefined ||
       pluginValue.credentialTypes !== undefined ||
+      pluginValue.mcpServers !== undefined ||
       pluginValue.sandbox !== undefined ||
       Object.keys(pluginValue).length === 0
     );