@codemation/host 0.5.1 → 0.7.0

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,45 @@ export class CodemationConsumerConfigLoader {
   private readonly performanceDiagnosticsLogger = new ServerLoggerFactory(
     logLevelPolicyFactory,
   ).createPerformanceDiagnostics("codemation-config-loader.timing");
+  /**
+   * 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 +91,33 @@ 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);
+    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 +190,9 @@ 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
     );

package/src/presentation/server/WorkflowDefinitionExportsResolver.ts

@@ -1,20 +1,38 @@
 import type { WorkflowDefinition } from "@codemation/core";
+import { WorkflowEdgePortValidator } from "@codemation/core";
 
 /**
  * Collects exported values that match the {@link WorkflowDefinition} shape.
  * Other exports (helpers, constants, type-only re-exports) are ignored.
+ *
+ * Throws if any workflow's edges reference output ports not declared by the
+ * source node config. All violations are reported at once so an agent can
+ * self-correct in a single pass.
  */
 export class WorkflowDefinitionExportsResolver {
+  private readonly portValidator = new WorkflowEdgePortValidator();
+
   resolve(moduleExports: Readonly<Record<string, unknown>>): ReadonlyArray<WorkflowDefinition> {
     const workflows: WorkflowDefinition[] = [];
     for (const exportedValue of Object.values(moduleExports)) {
       if (this.isWorkflowDefinition(exportedValue)) {
+        this.validatePorts(exportedValue);
         workflows.push(exportedValue);
       }
     }
     return workflows;
   }
 
+  private validatePorts(workflow: WorkflowDefinition): void {
+    const result = this.portValidator.validate(workflow);
+    if (!result.valid) {
+      const lines = result.errors.map((e) => `  - ${e.message}`).join("\n");
+      throw new Error(
+        `Workflow "${workflow.id}" ("${workflow.name}") has ${result.errors.length} invalid edge port(s):\n${lines}`,
+      );
+    }
+  }
+
   private isWorkflowDefinition(value: unknown): value is WorkflowDefinition {
     if (!value || typeof value !== "object") {
       return false;

package/src/presentation/server/WorkflowModulePathFinder.ts

@@ -42,6 +42,17 @@ export class WorkflowModulePathFinder {
 
   private isWorkflowModulePath(modulePath: string): boolean {
     const extension = path.extname(modulePath);
-    return this.workflowExtensions.has(extension) && !modulePath.endsWith(".d.ts");
+    if (!this.workflowExtensions.has(extension)) {
+      return false;
+    }
+    const basename = path.basename(modulePath);
+    if (basename.endsWith(".d.ts") || basename.endsWith(".d.mts")) {
+      return false;
+    }
+    const withoutExt = basename.slice(0, -extension.length);
+    if (withoutExt.endsWith(".test") || withoutExt.endsWith(".spec")) {
+      return false;
+    }
+    return true;
   }
 }

package/src/presentation/websocket/ManagedWebsocketAuthenticator.ts

@@ -0,0 +1,50 @@
+import { injectable } from "@codemation/core";
+import type { ManagedJwtVerifier, VerifiedManagedPrincipal } from "@codemation/managed-auth";
+import type { WebsocketAuthenticator } from "./WebsocketAuthenticator.types";
+
+/**
+ * WebSocket authenticator for `auth.kind: "managed"`.
+ *
+ * Parses `?token=<jwt>` from the WS upgrade URL and delegates to
+ * `ManagedJwtVerifier`.  Returns the verified principal on success or `null`
+ * when the token is missing, expired, has the wrong audience, or is otherwise
+ * invalid.
+ *
+ * Note: browsers cannot set `Authorization` headers on `new WebSocket(url)`,
+ * so the bearer is carried as a query-string parameter.
+ */
+@injectable()
+export class ManagedWebsocketAuthenticator implements WebsocketAuthenticator {
+  constructor(private readonly verifier: ManagedJwtVerifier) {}
+
+  async authenticate(requestUrl: string | undefined): Promise<VerifiedManagedPrincipal | null> {
+    if (!requestUrl) {
+      return null;
+    }
+
+    const token = this.extractToken(requestUrl);
+    if (!token) {
+      return null;
+    }
+
+    const result = await this.verifier.verify(token);
+    if ("failure" in result) {
+      return null;
+    }
+
+    return result;
+  }
+
+  private extractToken(requestUrl: string): string | null {
+    // requestUrl is a relative path like "/__codemation/internal/ws?token=..."
+    // Use a dummy base so URL can parse relative URLs.
+    let url: URL;
+    try {
+      url = new URL(requestUrl, "http://placeholder");
+    } catch {
+      return null;
+    }
+    const token = url.searchParams.get("token");
+    return token && token.length > 0 ? token : null;
+  }
+}

package/src/presentation/websocket/WebsocketAuthenticator.types.ts

@@ -0,0 +1,12 @@
+import type { VerifiedManagedPrincipal } from "@codemation/managed-auth";
+
+/**
+ * Authenticates an incoming WebSocket upgrade request.
+ *
+ * Implementations parse the upgrade URL (e.g. `?token=<jwt>`) and verify the
+ * credential.  Returns the verified principal on success, or `null` when the
+ * request must be rejected with close-code 4401.
+ */
+export interface WebsocketAuthenticator {
+  authenticate(requestUrl: string | undefined): Promise<VerifiedManagedPrincipal | null>;
+}

package/src/presentation/websocket/WorkflowWebsocketServer.ts

@@ -1,8 +1,10 @@
 import { WebSocket, WebSocketServer } from "ws";
+import type { IncomingMessage } from "node:http";
 import type { WorkflowWebsocketMessage } from "../../application/contracts/WorkflowWebsocketMessage";
 import type { Logger } from "../../application/logging/Logger";
 import type { WorkflowWebsocketPublisher } from "../../application/websocket/WorkflowWebsocketPublisher";
 import { ApiPaths } from "../http/ApiPaths";
+import type { WebsocketAuthenticator } from "./WebsocketAuthenticator.types";
 
 type WorkflowWebsocketClientMessage =
   | Readonly<{ kind: "subscribe"; roomId: string }>
@@ -26,8 +28,18 @@ export class WorkflowWebsocketServer implements WorkflowWebsocketPublisher {
     private readonly port: number,
     private readonly bindHost: string,
     private readonly logger: Logger,
+    private readonly authenticator: WebsocketAuthenticator | null = null,
   ) {}
 
+  /** Returns the actual port the server is listening on (useful when constructed with port 0). */
+  get listeningPort(): number {
+    const addr = this.websocketServer?.address();
+    if (!addr || typeof addr === "string") {
+      return this.port;
+    }
+    return addr.port;
+  }
+
   async start(): Promise<void> {
     if (this.started) {
       return;
@@ -38,8 +50,8 @@ export class WorkflowWebsocketServer implements WorkflowWebsocketPublisher {
       path: ApiPaths.workflowWebsocket(),
     });
     this.websocketServer = websocketServer;
-    websocketServer.on("connection", (socket) => {
-      void this.connect(socket);
+    websocketServer.on("connection", (socket, request) => {
+      void this.connect(socket, request);
     });
     try {
       await this.awaitListening(websocketServer);
@@ -98,7 +110,16 @@ export class WorkflowWebsocketServer implements WorkflowWebsocketPublisher {
     this.logger.debug(`published room=${roomId} sockets=${deliveredSocketCount} kind=${message.kind}`);
   }
 
-  private async connect(socket: WebSocket): Promise<void> {
+  private async connect(socket: WebSocket, request: IncomingMessage): Promise<void> {
+    if (this.authenticator) {
+      const principal = await this.authenticator.authenticate(request.url);
+      if (!principal) {
+        this.logger.warn("websocket auth failed: closing with 4401");
+        socket.close(4401, "unauthorized");
+        return;
+      }
+    }
+
     this.sockets.add(socket);
     this.roomIdsBySocket.set(socket, new Set());
     this.logger.debug(`client connected activeSockets=${this.sockets.size}`);

package/src/process/ExecaProcessRunner.ts

@@ -0,0 +1,41 @@
+import type { ChildProcess } from "node:child_process";
+import { execa, execaSync, type Options as ExecaOptions, type SyncOptions as ExecaSyncOptions } from "execa";
+
+import type { ProcessRunner, ProcessRunOptions, ProcessRunResult } from "./ProcessRunner.types";
+
+/**
+ * Production {@link ProcessRunner}. Defers cross-platform executable resolution (`pnpm` ↔ `pnpm.cmd`,
+ * `.cmd` / `.bat` / `.ps1` shims on Windows) and argument quoting to execa so call sites stop having
+ * to hand-roll platform conditionals.
+ */
+export class ExecaProcessRunner implements ProcessRunner {
+  spawn(command: string, args: ReadonlyArray<string>, options?: ProcessRunOptions): ChildProcess {
+    return execa(command, [...args], this.toExecaOptions(options)) as unknown as ChildProcess;
+  }
+
+  runSync(command: string, args: ReadonlyArray<string>, options?: ProcessRunOptions): ProcessRunResult {
+    const result = execaSync(command, [...args], this.toExecaSyncOptions(options));
+    return { exitCode: result.exitCode ?? null };
+  }
+
+  private toExecaOptions(options?: ProcessRunOptions): ExecaOptions {
+    return {
+      reject: false,
+      cwd: options?.cwd,
+      env: options?.env,
+      stdio: options?.stdio as ExecaOptions["stdio"],
+      detached: options?.detached,
+      windowsHide: options?.windowsHide,
+    };
+  }
+
+  private toExecaSyncOptions(options?: ProcessRunOptions): ExecaSyncOptions {
+    return {
+      reject: false,
+      cwd: options?.cwd,
+      env: options?.env,
+      stdio: options?.stdio as ExecaSyncOptions["stdio"],
+      windowsHide: options?.windowsHide,
+    };
+  }
+}

package/src/process/ProcessRunner.types.ts

@@ -0,0 +1,39 @@
+import type { ChildProcess } from "node:child_process";
+
+export type ProcessRunOptions = Readonly<{
+  cwd?: string;
+  env?: NodeJS.ProcessEnv;
+  /**
+   * Mirrors `child_process.SpawnOptions["stdio"]`. The runner forwards the value verbatim to the
+   * underlying subprocess, so callers that need fine-grained per-fd control (e.g.
+   * `["ignore", "pipe", "pipe"]`) can pass a tuple.
+   */
+  stdio?: "inherit" | "pipe" | "ignore" | ReadonlyArray<"inherit" | "pipe" | "ignore">;
+  /**
+   * On Unix this detaches the child from the parent's process group so it becomes the group
+   * leader (used by {@link DevTrackedProcessTreeKiller} to broadcast SIGTERM to descendants).
+   * On Windows it is ignored — `windowsHide` should be used to suppress console windows instead.
+   */
+  detached?: boolean;
+  windowsHide?: boolean;
+}>;
+
+export type ProcessRunResult = Readonly<{
+  exitCode: number | null;
+}>;
+
+/**
+ * Cross-platform process spawning seam. Implementations resolve bare CLI names (`pnpm`, `prisma`,
+ * `next`, …) against the OS PATH using OS-appropriate executable lookup, so call sites stop having
+ * to remember `pnpm.cmd` or `shell: true` on Windows.
+ *
+ * `spawn` returns a Node `ChildProcess` so existing helpers like `DevNextChildProcessOutputFilter`
+ * and `DevTrackedProcessTreeKiller` keep working unchanged.
+ */
+export interface ProcessRunner {
+  /** Long-lived child (dev watcher, Next dev server). Returns a `ChildProcess`. */
+  spawn(command: string, args: ReadonlyArray<string>, options?: ProcessRunOptions): ChildProcess;
+
+  /** Synchronous one-shot (used by Prisma migrate deploy). */
+  runSync(command: string, args: ReadonlyArray<string>, options?: ProcessRunOptions): ProcessRunResult;
+}

package/src/server.ts

@@ -1,5 +1,7 @@
 export { CodemationPostgresPrismaClientFactory } from "./persistenceServer";
 export type { PrismaClient } from "./persistenceServer";
+export { ExecaProcessRunner } from "./process/ExecaProcessRunner";
+export type { ProcessRunner, ProcessRunOptions, ProcessRunResult } from "./process/ProcessRunner.types";
 export { ApiPaths } from "./presentation/http/ApiPaths";
 export { CodemationServerGateway } from "./presentation/http/CodemationServerGatewayFactory";
 export { CodemationConsumerAppResolver } from "./presentation/server/CodemationConsumerAppResolver";

package/src/workflows/InternalWorkflowActivationRegistrar.ts

@@ -0,0 +1,42 @@
+import { inject, injectable } from "@codemation/core";
+import type { Hono } from "hono";
+import { ApplicationTokens } from "../applicationTokens";
+import type { CommandBus } from "../application/bus/CommandBus";
+import { SetWorkflowActivationCommand } from "../application/commands/SetWorkflowActivationCommand";
+import { InternalHmacAuthMiddleware } from "../pairing/InternalHmacAuthMiddleware";
+import type { InternalHonoApiRouteRegistrar } from "../presentation/http/hono/InternalHonoApiRouteRegistrar";
+
+/**
+ * Registers POST /internal/workflows/:workflowId/activation — HMAC-verified endpoint
+ * that activates or deactivates a workflow. Used by the coding agent to toggle workflow
+ * triggers without requiring a user session.
+ */
+@injectable()
+export class InternalWorkflowActivationRegistrar implements InternalHonoApiRouteRegistrar {
+  constructor(
+    @inject(InternalHmacAuthMiddleware) private readonly hmacMiddleware: InternalHmacAuthMiddleware,
+    @inject(ApplicationTokens.CommandBus) private readonly commandBus: CommandBus,
+  ) {}
+
+  register(app: Hono): void {
+    app.post("/internal/workflows/:workflowId/activation", this.hmacMiddleware.handle(), async (c) => {
+      const workflowId = c.req.param("workflowId");
+      let body: { active?: unknown };
+      try {
+        body = await c.req.json<{ active?: unknown }>();
+      } catch {
+        return c.json({ error: "Request body must be JSON with boolean active" }, 400);
+      }
+      if (typeof body.active !== "boolean") {
+        return c.json({ error: "Request body must include boolean active" }, 400);
+      }
+      try {
+        const result = await this.commandBus.execute(new SetWorkflowActivationCommand(workflowId, body.active));
+        return c.json(result);
+      } catch (err) {
+        const message = err instanceof Error ? err.message : String(err);
+        return c.json({ error: message }, 500);
+      }
+    });
+  }
+}

package/src/workflows/InternalWorkflowDetailRegistrar.ts

@@ -0,0 +1,33 @@
+import { inject, injectable } from "@codemation/core";
+import type { Hono } from "hono";
+import { ApplicationTokens } from "../applicationTokens";
+import type { QueryBus } from "../application/bus/QueryBus";
+import { GetWorkflowDetailQuery } from "../application/queries/GetWorkflowDetailQuery";
+import { WorkflowDefinitionMapper } from "../application/mapping/WorkflowDefinitionMapper";
+import { InternalHmacAuthMiddleware } from "../pairing/InternalHmacAuthMiddleware";
+import type { InternalHonoApiRouteRegistrar } from "../presentation/http/hono/InternalHonoApiRouteRegistrar";
+
+/**
+ * Registers GET /internal/workflows/:workflowId — HMAC-verified endpoint that returns a
+ * single workflow's full DAG (nodes + edges). Used by the concierge agent to inspect a
+ * specific workflow. Returns 404 (empty body) when the workflow id doesn't exist.
+ */
+@injectable()
+export class InternalWorkflowDetailRegistrar implements InternalHonoApiRouteRegistrar {
+  constructor(
+    @inject(InternalHmacAuthMiddleware) private readonly hmacMiddleware: InternalHmacAuthMiddleware,
+    @inject(ApplicationTokens.QueryBus) private readonly queryBus: QueryBus,
+    @inject(WorkflowDefinitionMapper) private readonly mapper: WorkflowDefinitionMapper,
+  ) {}
+
+  register(app: Hono): void {
+    app.get("/internal/workflows/:workflowId", this.hmacMiddleware.handle(), async (c) => {
+      const workflowId = c.req.param("workflowId");
+      const workflow = await this.queryBus.execute(new GetWorkflowDetailQuery(workflowId));
+      if (!workflow) {
+        return c.body(null, 404);
+      }
+      return c.json(await this.mapper.map(workflow));
+    });
+  }
+}