miravo 0.5.0 → 0.6.1

package/src/commands/start.ts

@@ -1,2253 +0,0 @@
-import { existsSync, readFileSync } from "node:fs";
-import { basename, resolve } from "node:path";
-import type { Option as ClackOption } from "@clack/prompts";
-import { isCancel, select } from "@clack/prompts";
-import type { ContentCatalog, ControlPlane, Engine, TwinRuntime } from "@miravo/core";
-import {
-  createControlPlane,
-  createEngine,
-  discoverTemplates,
-  loadTemplate,
-  loadTwinModel,
-  resolveMiravoHome,
-  resolveModelPath,
-  validateFullTemplate,
-} from "@miravo/core";
-import { ModbusAdapter } from "@miravo/modbus";
-import { MQTTAdapter } from "@miravo/mqtt";
-import { OPCUAAdapter } from "@miravo/opcua";
-import type {
-  CatalogTemplate,
-  DiscoveredTemplate,
-  MiravoTemplate,
-  TemplateRun,
-  TwinModel,
-} from "@miravo/shared";
-import {
-  ConfigNotFoundError,
-  ConfigValidationError,
-  DEFAULT_MODBUS_PORT,
-  DEFAULT_MQTT_PORT,
-  DEFAULT_OPCUA_PORT,
-  DEFAULT_TICK_INTERVAL_MS,
-  DEFAULT_TIME_MULTIPLIER,
-  MIRAVO_VERSION,
-  MiravoError,
-  MiravoTemplateSchema,
-  PersistedStateSchema,
-  SimulationNameSchema,
-  TWIN_FILE_EXTENSION,
-  TwinModelSchema,
-} from "@miravo/shared";
-import { Glob } from "bun";
-import type { Command } from "commander";
-import { box, colors, stripAnsi } from "consola/utils";
-import { parse as parseYAML } from "yaml";
-import { startAdminServer } from "../lib/admin-server.ts";
-import type { DaemonRegistryEntry } from "../lib/daemon-registry.ts";
-import {
-  acquireNameLock,
-  checkNameConflict,
-  checkPortConflicts,
-  displayHost,
-  isPidAlive,
-  writeEntry,
-} from "../lib/daemon-registry.ts";
-import {
-  parseDurationMs,
-  parseNonNegativeInt,
-  parsePort,
-  parsePositiveFloat,
-  parsePositiveInt,
-} from "../lib/parse.ts";
-import { createShutdownController, printSummaryLine } from "../lib/shutdown.ts";
-import {
-  groupTemplatesByCategory,
-  isStressBenchmarkTemplate,
-  sortTemplatesByCategoryAndName,
-} from "../lib/template-category.ts";
-import {
-  createCatalog,
-  discoverPreferredLocalTemplates,
-  isTemplatePathLike,
-  resolveTemplateIdentifier,
-} from "../lib/template-locator.ts";
-import { buildUNSBasePath, collectReferencedModels, forEachTwin } from "../lib/template-utils.ts";
-import {
-  clearRuntimeLogContext,
-  configLog,
-  controlLog,
-  engineLog,
-  faultLog,
-  handleCommandError,
-  isPlain,
-  lifecycleLog,
-  modbusLog,
-  mqttLog,
-  opcuaLog,
-  setRuntimeLogContext,
-  writeOutput,
-} from "../logger.ts";
-import { formatKeyValue, formatTable } from "../output.ts";
-
-interface StartOptions {
-  readonly name?: string;
-  readonly template?: string;
-  readonly modelsDir?: string;
-  readonly speed?: number;
-  readonly seed?: number;
-  readonly tick?: number;
-  readonly mqttPort?: number;
-  readonly mqttHost?: string;
-  readonly mqttMode?: string;
-  readonly mqttUrl?: string;
-  readonly mqttUsername?: string;
-  readonly mqttPassword?: string;
-  readonly mqtt?: boolean;
-  readonly opcuaPort?: number;
-  readonly opcuaHost?: string;
-  readonly opcua?: boolean;
-  readonly modbusPort?: number;
-  readonly modbusHost?: string;
-  readonly modbus?: boolean;
-  readonly adminHost?: string;
-  readonly adminPort?: number;
-  readonly dryRun?: boolean;
-  readonly summaryInterval?: number;
-  readonly noUi?: boolean;
-  readonly resetState?: boolean;
-  readonly detach?: boolean;
-  readonly command?: Command;
-}
-
-interface RestoreSummary {
-  readonly instanceCount: number;
-  readonly templateRunCount: number;
-  readonly adapterCount: number;
-}
-
-interface ProtocolBootPlan {
-  readonly name: "mqtt" | "opcua" | "modbus";
-  readonly shouldEnable: boolean;
-  readonly overrideRestore: boolean;
-}
-
-type ProtocolOptionSource =
-  | "mqtt"
-  | "opcua"
-  | "modbus"
-  | "mqttPort"
-  | "mqttHost"
-  | "mqttMode"
-  | "mqttUrl"
-  | "mqttUsername"
-  | "mqttPassword"
-  | "opcuaPort"
-  | "opcuaHost"
-  | "modbusPort"
-  | "modbusHost";
-
-type MqttMode = "embedded" | "external";
-
-/** Resolve the path to the built console dist directory. Returns undefined if not found. */
-function resolveConsoleDir(): string | undefined {
-  // 1. Compiled standalone binary: Bun.main resolves to a /$bunfs/ virtual path.
-  //    Look for console-dist/ packaged alongside the binary.
-  if (Bun.main.startsWith("/$bunfs/")) {
-    const binaryDir = new URL(".", `file://${process.execPath}`).pathname.replace(/\/$/, "");
-    const sibling = `${binaryDir}/console-dist`;
-    if (Bun.file(`${sibling}/index.html`).size > 0) return sibling;
-  }
-
-  // 2. Dev / Docker: resolve via workspace package (@miravo/console is a devDependency,
-  //    available in workspace but not when installed from npm).
-  try {
-    const resolved = import.meta.resolve("@miravo/console");
-    const resolvedDir = new URL(".", resolved).pathname.replace(/\/$/, "");
-    if (resolvedDir.endsWith("/dist")) return resolvedDir;
-    return `${resolvedDir}/dist`;
-  } catch {
-    // @miravo/console not installed (npm/bunx) — fall through
-  }
-
-  // 3. Docker / monorepo: workspace symlinks may not exist (production install).
-  //    start.ts is at packages/cli/src/commands/ → ../../../console/dist
-  const monorepo = resolve(import.meta.dir, "..", "..", "..", "console", "dist");
-  if (existsSync(`${monorepo}/index.html`)) return monorepo;
-
-  // 4. npm install / bunx: look for console-dist/ shipped inside the published package.
-  //    start.ts is at packages/cli/src/commands/ → ../../console-dist/
-  const shipped = resolve(import.meta.dir, "..", "..", "console-dist");
-  if (existsSync(`${shipped}/index.html`)) return shipped;
-
-  return undefined;
-}
-
-interface MqttRunOverrides {
-  readonly mode?: MqttMode;
-  readonly host?: string;
-  readonly url?: string;
-  readonly username?: string;
-  readonly password?: string;
-  readonly drainBudget?: number;
-  readonly batchSize?: number;
-  readonly brokerConcurrency?: number;
-}
-
-const MAX_ERROR_CONTEXT_KEYS = 256;
-const ERROR_CONTEXT_OVERFLOW = "__overflow__";
-
-/**
- * Register the `miravo start` command with the root Commander program.
- * Resolves template, creates the engine, starts MQTT, and runs the simulation loop.
- */
-export function registerStartCommand(program: Command): void {
-  program
-    .command("start")
-    .description("Start a simulation from a template")
-    .option("-n, --name <name>", "Simulation name (env: MIRAVO_NAME, flag takes precedence)")
-    .option(
-      "-t, --template <id|name|path,...>",
-      "Template id, name, path, or comma-separated list (env: MIRAVO_TEMPLATE, flag takes precedence)",
-    )
-    .option("--models-dir <path>", "Additional directory to search for .twin.yaml models")
-    .option("-s, --speed <multiplier>", "Time multiplier (default: 1)", parsePositiveFloat)
-    .option("--seed <number>", "RNG seed for deterministic simulation", parseNonNegativeInt)
-    .option("--tick <ms>", "Tick interval in milliseconds (default: 1000)", parseDurationMs)
-    .option(
-      "-p, --mqtt-port <number>",
-      "MQTT broker port (default: 1883, env: MIRAVO_MQTT_PORT)",
-      parsePort,
-    )
-    .option("--mqtt-host <host>", "MQTT bind host (default: 127.0.0.1, env: MIRAVO_MQTT_HOST)")
-    .option("--mqtt-mode <mode>", "MQTT mode: embedded | external (env: MIRAVO_MQTT_MODE)")
-    .option("--mqtt-url <url>", "External MQTT broker URL (env: MIRAVO_MQTT_URL)")
-    .option("--mqtt-username <username>", "External MQTT username (env: MIRAVO_MQTT_USERNAME)")
-    .option("--mqtt-password <password>", "External MQTT password (env: MIRAVO_MQTT_PASSWORD)")
-    .option("--no-mqtt", "Disable MQTT broker")
-    .option("--opcua", "Enable OPC UA server")
-    .option(
-      "--opcua-port <number>",
-      "OPC UA server port (default: 4840, env: MIRAVO_OPCUA_PORT)",
-      parsePort,
-    )
-    .option("--opcua-host <host>", "OPC UA server bind host (env: MIRAVO_OPCUA_HOST)")
-    .option("--modbus", "Enable Modbus TCP server adapter")
-    .option(
-      "--modbus-port <number>",
-      `Modbus TCP port (default: ${DEFAULT_MODBUS_PORT}, env: MIRAVO_MODBUS_PORT)`,
-      parsePort,
-    )
-    .option("--modbus-host <host>", "Modbus TCP bind host (env: MIRAVO_MODBUS_HOST)")
-    .option("--admin-host <host>", "Admin server host (default: 127.0.0.1, env: MIRAVO_ADMIN_HOST)")
-    .option(
-      "--admin-port <number>",
-      "Admin server port (default: 8080, env: MIRAVO_ADMIN_PORT)",
-      parsePort,
-    )
-    .option("-d, --detach", "Start simulation in background (daemon mode)")
-    .option("--dry-run", "Validate config and print summary without starting")
-    .option("--no-ui", "Disable the embedded web console")
-    .option("--reset-state", "Reset persisted state — start fresh (ignore any saved snapshot)")
-    .option(
-      "--summary-interval <seconds>",
-      "Seconds between periodic summary lines (default: 5)",
-      parsePositiveInt,
-    )
-    .addHelpText(
-      "after",
-      `
-Examples:
-  $ miravo start                                   Start with auto-detected template
-  $ miravo start -t water-treatment                Start a specific template
-  $ miravo start -t smart-factory,water-treatment  Start with two templates
-  $ miravo start -d --name my-sim                  Start in background (daemon mode)
-  $ miravo start -s 10 --seed 42                   Run at 10x speed with fixed seed
-  $ miravo start --no-mqtt --opcua                 Disable MQTT, enable OPC UA
-  $ miravo start --dry-run                         Validate and print summary only`,
-    )
-    .action(async (options: StartOptions, command: Command) => {
-      await startAction({ ...options, command });
-    });
-}
-
-// ---------------------------------------------------------------------------
-// Start action orchestration
-// ---------------------------------------------------------------------------
-
-async function startAction(options: StartOptions): Promise<void> {
-  let runtimeLogContextSet = false;
-  let shutdown: ReturnType<typeof createShutdownController> | null = null;
-  let engine: Engine | undefined;
-  let stopCliResources = (): void => {};
-  try {
-    const catalog = createCatalog();
-
-    // Resolve env-var fallbacks for common options
-    const templateOptionRaw = options.template ?? Bun.env["MIRAVO_TEMPLATE"];
-    // Support comma-separated template identifiers: first is the boot template, rest loaded after startup
-    const templateParts: string[] = templateOptionRaw
-      ? templateOptionRaw
-          .split(",")
-          .map((s) => s.trim())
-          .filter(Boolean)
-      : [];
-    const templateOption: string | undefined = templateParts[0];
-    const extraTemplateIdentifiers: string[] = templateParts.slice(1);
-    const simulationNameEnv = Bun.env["MIRAVO_NAME"];
-    // Protocol selection: CLI flags decide which protocols run
-    const mqttEnabled = options.mqtt !== false; // --no-mqtt disables
-    const opcuaEnabled = options.opcua === true; // --opcua enables
-    const modbusEnabled = options.modbus === true; // --modbus enables
-
-    // Warn on ignored protocol-specific flags
-    if (!mqttEnabled) {
-      if (options.mqttPort !== undefined) {
-        configLog.warn("--mqtt-port ignored because MQTT is disabled.");
-      }
-      if (options.mqttHost !== undefined) {
-        configLog.warn("--mqtt-host ignored because MQTT is disabled.");
-      }
-      if (options.mqttMode !== undefined) {
-        configLog.warn("--mqtt-mode ignored because MQTT is disabled.");
-      }
-    }
-    if (!opcuaEnabled) {
-      if (options.opcuaPort !== undefined) {
-        configLog.warn(
-          "--opcua-port ignored because OPC UA is not enabled. Use --opcua to enable it.",
-        );
-      }
-      if (options.opcuaHost !== undefined) {
-        configLog.warn(
-          "--opcua-host ignored because OPC UA is not enabled. Use --opcua to enable it.",
-        );
-      }
-    }
-    if (!modbusEnabled) {
-      if (options.modbusPort !== undefined) {
-        configLog.warn(
-          "--modbus-port ignored because Modbus is not enabled. Use --modbus to enable it.",
-        );
-      }
-      if (options.modbusHost !== undefined) {
-        configLog.warn(
-          "--modbus-host ignored because Modbus is not enabled. Use --modbus to enable it.",
-        );
-      }
-    }
-
-    const adminHost = options.adminHost ?? Bun.env["MIRAVO_ADMIN_HOST"] ?? "127.0.0.1";
-    const adminPortEnv = Bun.env["MIRAVO_ADMIN_PORT"];
-    if (adminHost.trim().length === 0) {
-      throw new ConfigValidationError({
-        message: "Invalid admin server host: value is empty.",
-        fix: "Set --admin-host / MIRAVO_ADMIN_HOST to a valid host (for example, 127.0.0.1 or 0.0.0.0).",
-      });
-    }
-
-    // MQTT env overrides — only parsed when MQTT is enabled
-    let portOption = options.mqttPort;
-    let mqttOverrides: MqttRunOverrides = {};
-    if (mqttEnabled) {
-      const portEnv = Bun.env["MIRAVO_MQTT_PORT"];
-      const mqttHost = options.mqttHost ?? Bun.env["MIRAVO_MQTT_HOST"];
-      const mqttMode = parseMqttModeOption(options.mqttMode ?? Bun.env["MIRAVO_MQTT_MODE"]);
-      const mqttUrl = options.mqttUrl ?? Bun.env["MIRAVO_MQTT_URL"];
-      const mqttUsername = options.mqttUsername ?? Bun.env["MIRAVO_MQTT_USERNAME"];
-      const mqttPassword = options.mqttPassword ?? Bun.env["MIRAVO_MQTT_PASSWORD"];
-      // Tuning env vars for adapter performance
-      const drainBudgetEnv = Bun.env["MIRAVO_MQTT_DRAIN_BUDGET"];
-      const batchSizeEnv = Bun.env["MIRAVO_MQTT_BATCH_SIZE"];
-      const brokerConcurrencyEnv = Bun.env["MIRAVO_MQTT_BROKER_CONCURRENCY"];
-      const drainBudget = drainBudgetEnv ? parsePositiveInt(drainBudgetEnv) : undefined;
-      const batchSize = batchSizeEnv ? parsePositiveInt(batchSizeEnv) : undefined;
-      const brokerConcurrency = brokerConcurrencyEnv
-        ? parsePositiveInt(brokerConcurrencyEnv)
-        : undefined;
-      mqttOverrides = {
-        ...(mqttMode !== undefined ? { mode: mqttMode } : {}),
-        ...(mqttHost !== undefined && mqttHost.length > 0 ? { host: mqttHost } : {}),
-        ...(mqttUrl !== undefined && mqttUrl.length > 0 ? { url: mqttUrl } : {}),
-        ...(mqttUsername !== undefined && mqttUsername.length > 0
-          ? { username: mqttUsername }
-          : {}),
-        ...(mqttPassword !== undefined && mqttPassword.length > 0
-          ? { password: mqttPassword }
-          : {}),
-        ...(drainBudget !== undefined ? { drainBudget } : {}),
-        ...(batchSize !== undefined ? { batchSize } : {}),
-        ...(brokerConcurrency !== undefined ? { brokerConcurrency } : {}),
-      };
-      if (portOption === undefined && portEnv) {
-        try {
-          portOption = parsePort(portEnv);
-        } catch {
-          throw new ConfigValidationError({
-            message: `Invalid MIRAVO_MQTT_PORT environment variable: "${portEnv}".`,
-            fix: "Set MIRAVO_MQTT_PORT to a valid port number between 1 and 65535 (for example, 1883).",
-          });
-        }
-      }
-      if (mqttHost !== undefined && mqttHost.trim().length === 0) {
-        throw new ConfigValidationError({
-          message: "Invalid MQTT bind host: value is empty.",
-          fix: "Set --mqtt-host / MIRAVO_MQTT_HOST to a valid host (for example, 127.0.0.1 or 0.0.0.0).",
-        });
-      }
-    }
-
-    // OPC UA env overrides — only parsed when OPC UA is enabled
-    let opcuaPort: number | undefined = options.opcuaPort;
-    let opcuaHost: string | undefined;
-    let opcuaWriteBudget: number | undefined;
-    if (opcuaEnabled) {
-      const opcuaPortEnv = Bun.env["MIRAVO_OPCUA_PORT"];
-      if (opcuaPort === undefined && opcuaPortEnv) {
-        try {
-          opcuaPort = parsePort(opcuaPortEnv);
-        } catch {
-          throw new ConfigValidationError({
-            message: `Invalid MIRAVO_OPCUA_PORT environment variable: "${opcuaPortEnv}".`,
-            fix: "Set MIRAVO_OPCUA_PORT to a valid port number between 1 and 65535 (for example, 4840).",
-          });
-        }
-      }
-      opcuaHost = options.opcuaHost ?? Bun.env["MIRAVO_OPCUA_HOST"] ?? undefined;
-      if (opcuaHost !== undefined && opcuaHost.trim().length === 0) {
-        throw new ConfigValidationError({
-          message: "Invalid OPC UA bind host: value is empty.",
-          fix: "Set --opcua-host / MIRAVO_OPCUA_HOST to a valid host (for example, 0.0.0.0).",
-        });
-      }
-      const writeBudgetEnv = Bun.env["MIRAVO_OPCUA_WRITE_BUDGET"];
-      if (writeBudgetEnv) {
-        opcuaWriteBudget = parsePositiveInt(writeBudgetEnv);
-      }
-    }
-
-    // Modbus env overrides — only parsed when Modbus is enabled
-    let modbusPort: number | undefined = options.modbusPort;
-    let modbusHost: string | undefined;
-    if (modbusEnabled) {
-      const modbusPortEnv = Bun.env["MIRAVO_MODBUS_PORT"];
-      if (modbusPort === undefined && modbusPortEnv) {
-        try {
-          modbusPort = parsePort(modbusPortEnv);
-        } catch {
-          throw new ConfigValidationError({
-            message: `Invalid MIRAVO_MODBUS_PORT environment variable: "${modbusPortEnv}".`,
-            fix: "Set MIRAVO_MODBUS_PORT to a valid port number between 0 and 65535.",
-          });
-        }
-      }
-      modbusHost = options.modbusHost ?? Bun.env["MIRAVO_MODBUS_HOST"] ?? undefined;
-      if (modbusHost !== undefined && modbusHost.trim().length === 0) {
-        throw new ConfigValidationError({
-          message: "Invalid Modbus TCP bind host: value is empty.",
-          fix: "Set --modbus-host / MIRAVO_MODBUS_HOST to a valid host (for example, 0.0.0.0 or 127.0.0.1).",
-        });
-      }
-    }
-
-    let adminPort = options.adminPort;
-    if (adminPort === undefined && adminPortEnv) {
-      try {
-        adminPort = parsePort(adminPortEnv);
-      } catch {
-        throw new ConfigValidationError({
-          message: `Invalid MIRAVO_ADMIN_PORT environment variable: "${adminPortEnv}".`,
-          fix: "Set MIRAVO_ADMIN_PORT to a valid port number between 1 and 65535 (for example, 8080).",
-        });
-      }
-    }
-    adminPort ??= 8080;
-
-    // Step 1: Resolve template path(s)
-    // If the simulation name is explicitly known and no template was given,
-    // peek at persisted state to recover the template path — skipping the
-    // interactive picker on resume.
-    let effectiveTemplateOption = templateOption;
-    if (!effectiveTemplateOption && !options.resetState) {
-      const knownName = options.name ?? simulationNameEnv;
-      if (knownName) {
-        // Named: peek by explicit simulation name
-        const peeked = await peekStateTemplatePath(knownName);
-        if (peeked) {
-          effectiveTemplateOption = peeked;
-          configLog.debug(`Resuming from persisted state: template=${peeked}`);
-        }
-      } else {
-        // Unnamed: scan state dir — auto-resume if exactly one simulation exists
-        const peeked = await peekSingleStateTemplatePath();
-        if (peeked) {
-          effectiveTemplateOption = peeked;
-          configLog.debug(`Resuming from persisted state: template=${peeked}`);
-        }
-      }
-    }
-    const templatePath = await resolveTemplatePath(effectiveTemplateOption, catalog);
-    configLog.debug(`Resolved template: ${templatePath}`);
-    // Resolve any additional comma-separated templates upfront so errors surface before engine start
-    const extraTemplatePaths = await Promise.all(
-      extraTemplateIdentifiers.map((id) => resolveTemplateIdentifier(id, catalog)),
-    );
-
-    // Step 2: Load and validate
-    const { template, models, seed, seedExplicit } = await loadAndValidateTemplate(
-      templatePath,
-      options,
-      catalog,
-    );
-    const simulationName = resolveSimulationName({
-      template,
-      ...(options.name !== undefined ? { cliName: options.name } : {}),
-      ...(simulationNameEnv !== undefined ? { envName: simulationNameEnv } : {}),
-    });
-    configLog.debug(`Loaded ${models.size} models, seed=${seed} (explicit=${seedExplicit})`);
-    controlLog.info(`Simulation name: ${simulationName}`);
-
-    // Step 3: Dry-run check
-    if (options.dryRun) {
-      printDryRunSummary(template, models, seed, seedExplicit, templatePath);
-      return;
-    }
-
-    // Step 3b: Detach check — spawn background process and exit
-    if (options.detach) {
-      const detachAdapterConfigs = resolveDetachAdapterConfigs({
-        template,
-        simulationName,
-        mqtt: {
-          enabled: mqttEnabled,
-          portOverride: portOption,
-          overrides: mqttOverrides,
-        },
-        opcua: {
-          enabled: opcuaEnabled,
-          portOverride: opcuaPort,
-          hostOverride: opcuaHost,
-          writeBudgetOverride: opcuaWriteBudget,
-        },
-        modbus: {
-          enabled: modbusEnabled,
-          portOverride: modbusPort,
-          hostOverride: modbusHost,
-        },
-      });
-
-      await detachAction({
-        simulationName,
-        templatePath,
-        seed,
-        seedExplicit,
-        adminHost,
-        adminPort,
-        mqttPort: detachAdapterConfigs.mqtt.port,
-        mqttHost: detachAdapterConfigs.mqtt.host,
-        mqttEmbedded: detachAdapterConfigs.mqtt.embedded,
-        mqttEnabled,
-        opcuaPort: detachAdapterConfigs.opcua.port,
-        opcuaHost: detachAdapterConfigs.opcua.host,
-        opcuaEnabled,
-        modbusPort: detachAdapterConfigs.modbus.port,
-        modbusHost: detachAdapterConfigs.modbus.host,
-        modbusEnabled,
-      });
-      return;
-    }
-
-    const runId = Bun.env["MIRAVO_DAEMON_RUN_ID"] ?? crypto.randomUUID();
-    setRuntimeLogContext({ simulationName, runId });
-    runtimeLogContextSet = true;
-    controlLog.info(`Run ID: ${runId}`);
-
-    shutdown = createShutdownController({
-      seed,
-      seedExplicit,
-    });
-    const shutdownRequested = shutdown.waitForShutdownRequest();
-    shutdown.addTask("finalize", "runtime log context", () => {
-      if (runtimeLogContextSet) {
-        clearRuntimeLogContext();
-        runtimeLogContextSet = false;
-      }
-    });
-
-    // Step 4: Create engine and populate
-    engine = createAndPopulateEngine(
-      template,
-      models,
-      catalog,
-      seed,
-      options,
-      templatePath,
-      simulationName,
-    );
-    shutdown.setEngine(engine);
-
-    // Wire up template loader for runtime loadTemplate commands
-    // Single discovery pass builds both the path cache and catalog (avoids re-reading YAML)
-    const { pathCache: templatePathCache, catalog: catalogTemplates } =
-      await buildTemplateCacheAndCatalog(catalog);
-    engine.setTemplateLoader(createRuntimeTemplateLoader(catalog, templatePathCache));
-
-    // Load any additional comma-separated templates as extra template runs
-    for (const extraPath of extraTemplatePaths) {
-      const result = await engine.execute({
-        type: "loadTemplate",
-        templatePath: extraPath,
-        count: 1,
-      });
-      if (!result.success) {
-        throw new MiravoError(
-          `Failed to load additional template "${extraPath}": ${result.message}`,
-          result.error ?? "Check that the template is valid and compatible.",
-        );
-      }
-      configLog.info(`Loaded additional template: ${extraPath}`);
-    }
-
-    let controlPlane: ControlPlane | null = null;
-    let adminServer: { endpoint: string; stop: () => void } | null = null;
-    let lastTickProgressAt = performance.now();
-    let tickProgressSubscribed = false;
-    const onTickProgress = (): void => {
-      lastTickProgressAt = performance.now();
-    };
-    let unsubscribeEvents = (): void => {};
-    let summaryTimer: ReturnType<typeof setInterval> | null = null;
-
-    stopCliResources = (): void => {
-      controlPlane?.stop();
-      adminServer?.stop();
-      if (summaryTimer !== null) {
-        clearInterval(summaryTimer);
-        summaryTimer = null;
-      }
-      if (tickProgressSubscribed && engine) {
-        engine.bus.off("tick:complete", onTickProgress);
-        tickProgressSubscribed = false;
-      }
-      unsubscribeEvents();
-    };
-
-    shutdown.addTask("cleanup", "CLI resources", stopCliResources);
-
-    // Step 5: Register adapter factories and enable active adapters
-    // Track the last created MQTT adapter via closure (needed for control plane transport)
-    let lastCreatedMqttAdapter: MQTTAdapter | null = null;
-    const eng = engine; // const alias for closures (engine is `let` and TS can't narrow across closures)
-
-    const mqttDefaultConfig = buildMQTTDefaultConfig(
-      template,
-      portOption,
-      mqttOverrides,
-      simulationName,
-    );
-    eng.registerAvailableAdapter(
-      "mqtt",
-      async (config) => {
-        const adapter = new MQTTAdapter(eng.bus);
-        await adapter.start(config);
-        lastCreatedMqttAdapter = adapter;
-        return { adapter, endpoint: buildMQTTEndpoint(config) };
-      },
-      mqttDefaultConfig,
-    );
-
-    const opcuaDefaultConfig = buildOPCUADefaultConfig(
-      template,
-      opcuaPort,
-      opcuaHost,
-      simulationName,
-      opcuaWriteBudget,
-    );
-    eng.registerAvailableAdapter(
-      "opcua",
-      async (config) => {
-        const adapter = new OPCUAAdapter(eng.bus, eng);
-        await adapter.start(config);
-        return { adapter, endpoint: buildOPCUAEndpoint(config) };
-      },
-      opcuaDefaultConfig,
-    );
-
-    const modbusDefaultConfig = buildModbusDefaultConfig(template, modbusPort, modbusHost);
-    eng.registerAvailableAdapter(
-      "modbus",
-      async (config) => {
-        const adapter = new ModbusAdapter(eng.bus, eng);
-        await adapter.start(config);
-        return { adapter, endpoint: buildModbusEndpoint(config) };
-      },
-      modbusDefaultConfig,
-    );
-
-    // Step 5b: Wire control plane (dynamically follows MQTT adapter lifecycle)
-    function wireControlPlane(): void {
-      // Stop old control plane before creating a new one (prevents listener leaks)
-      if (controlPlane) {
-        controlPlane.stop();
-        controlPlane = null;
-      }
-      const mqttAdapter = lastCreatedMqttAdapter as MQTTAdapter | null;
-      if (!mqttAdapter) return;
-      const transport = mqttAdapter.getControlTransport();
-      if (!transport) return;
-      controlPlane = createControlPlane({
-        simulationName,
-        engine: eng,
-        transport,
-        bus: eng.bus,
-      });
-      controlPlane.start();
-      controlLog.info(`active on $miravo/${simulationName}/* topics`);
-    }
-
-    // Wire now if MQTT was enabled at boot
-    wireControlPlane();
-
-    // Re-wire on runtime MQTT enable, tear down on disable
-    eng.bus.on("adapter:enabled", (evt) => {
-      if (evt.name === "mqtt") wireControlPlane();
-    });
-    eng.bus.on("adapter:disabled", (evt) => {
-      if (evt.name === "mqtt") {
-        controlPlane?.stop();
-        controlPlane = null;
-        lastCreatedMqttAdapter = null;
-        controlLog.info("control plane stopped (MQTT adapter disabled)");
-      }
-    });
-
-    // Step 5c: Subscribe to events + periodic summary before engine.start() so restore events are visible
-    const errorContextCounts = new Map<string, number>();
-    unsubscribeEvents = subscribeToEvents(eng, errorContextCounts);
-    shutdown.setErrorContextCounts(errorContextCounts);
-    const summaryInterval = options.summaryInterval ?? 5;
-    summaryTimer = startPeriodicSummary(eng, summaryInterval);
-
-    eng.bus.on("tick:complete", onTickProgress);
-    tickProgressSubscribed = true;
-
-    let restoredState: RestoreSummary | null = null;
-    const onRestored = (event: RestoreSummary): void => {
-      restoredState = event;
-    };
-    eng.bus.on("engine:restored", onRestored);
-    try {
-      await eng.start();
-    } finally {
-      eng.bus.off("engine:restored", onRestored);
-    }
-
-    // Step 6: Start admin HTTP server after restore + adapter reconciliation
-    try {
-      adminServer = startAdminServer({
-        engine: eng,
-        network: {
-          host: adminHost,
-          port: adminPort,
-          tickIntervalMs: eng.getState().config.tickIntervalMs,
-        },
-        protocols: {
-          getLastTickProgressAt: () => lastTickProgressAt,
-        },
-        ws: {
-          bus: eng.bus,
-          getEngineState: () => eng.getMetrics().core.state,
-          getTickInfo: () => {
-            const core = eng.getMetrics().core;
-            return {
-              tick: core.tickCount,
-              simulationTime: core.simulationTimeSeconds,
-              instanceCount: core.instanceCount,
-            };
-          },
-        },
-        adminToken: Bun.env["MIRAVO_ADMIN_TOKEN"],
-        consoleDir: options.noUi ? undefined : resolveConsoleDir(),
-        getCatalog: () => catalogTemplates,
-        simulationName,
-        runId,
-        requestShutdown: (reason) => shutdown?.requestShutdown(reason),
-      });
-      controlLog.info(`admin server ready · endpoint: ${colors.cyan(adminServer.endpoint)}`);
-    } catch (error) {
-      const message = error instanceof Error ? error.message : String(error);
-      throw new MiravoError(
-        `Admin server failed to start on ${adminHost}:${adminPort}: ${message}`,
-        "Set --admin-port / MIRAVO_ADMIN_PORT to a free port, or change --admin-host.",
-      );
-    }
-
-    // Step 7: Print startup banner from the post-restore runtime state
-    const availableAdapters = eng.getAvailableAdapters();
-    const mqttEndpoint =
-      availableAdapters.find((a) => a.name === "mqtt" && a.enabled)?.endpoint ?? null;
-    const opcuaEndpoint =
-      availableAdapters.find((a) => a.name === "opcua" && a.enabled)?.endpoint ?? null;
-    const modbusEndpoint =
-      availableAdapters.find((a) => a.name === "modbus" && a.enabled)?.endpoint ?? null;
-    printStartupBanner(
-      templatePath,
-      eng,
-      seed,
-      seedExplicit,
-      mqttEndpoint,
-      opcuaEndpoint,
-      modbusEndpoint,
-      simulationName,
-      runId,
-      adminServer.endpoint,
-    );
-
-    const restoreSummary = restoredState as RestoreSummary | null;
-    if (restoreSummary !== null) {
-      engineLog.info(
-        `restored saved state · ${colors.bold(String(restoreSummary.instanceCount))} instances · ${colors.bold(String(restoreSummary.templateRunCount))} template runs · ${colors.bold(String(restoreSummary.adapterCount))} adapters`,
-      );
-    } else if (options.resetState) {
-      engineLog.info("starting fresh (--reset-state)");
-    }
-
-    shutdown.markRunning();
-    engineLog.success("Simulation started.");
-    await shutdownRequested;
-    await shutdown.runShutdown();
-    shutdown.teardown();
-  } catch (error) {
-    if (shutdown?.isShuttingDown()) {
-      await shutdown.runShutdown();
-      shutdown.teardown();
-      return;
-    }
-    shutdown?.teardown();
-    stopCliResources();
-    try {
-      await engine?.stop("boot error");
-    } catch {
-      // engine may not exist yet or stop may fail — swallow
-    }
-    if (runtimeLogContextSet) {
-      clearRuntimeLogContext();
-      runtimeLogContextSet = false;
-    }
-    handleCommandError(error);
-  }
-}
-
-// ---------------------------------------------------------------------------
-// Detach mode — spawn background simulation
-// ---------------------------------------------------------------------------
-
-interface DetachOptions {
-  readonly simulationName: string;
-  readonly templatePath: string;
-  readonly seed: number;
-  readonly seedExplicit: boolean;
-  readonly adminHost: string;
-  readonly adminPort: number;
-  readonly mqttPort: number | undefined;
-  readonly mqttHost: string | undefined;
-  readonly mqttEmbedded: boolean;
-  readonly mqttEnabled: boolean;
-  readonly opcuaPort: number | undefined;
-  readonly opcuaHost: string | undefined;
-  readonly opcuaEnabled: boolean;
-  readonly modbusPort: number | undefined;
-  readonly modbusHost: string | undefined;
-  readonly modbusEnabled: boolean;
-}
-
-interface ResolvedDetachAdapterConfigs {
-  readonly mqtt: {
-    readonly port: number | undefined;
-    readonly host: string | undefined;
-    readonly embedded: boolean;
-  };
-  readonly opcua: {
-    readonly port: number | undefined;
-    readonly host: string | undefined;
-  };
-  readonly modbus: {
-    readonly port: number | undefined;
-    readonly host: string | undefined;
-  };
-}
-
-async function detachAction(opts: DetachOptions): Promise<void> {
-  const { simulationName } = opts;
-
-  // 1. Acquire exclusive lock to prevent concurrent starts
-  const releaseLock = await acquireNameLock(simulationName);
-  try {
-    await detachActionLocked(opts, releaseLock);
-  } catch (error) {
-    await releaseLock();
-    throw error;
-  }
-}
-
-async function detachActionLocked(
-  opts: DetachOptions,
-  releaseLock: () => Promise<void>,
-): Promise<void> {
-  const { simulationName, adminHost, adminPort } = opts;
-
-  // 1. Check name conflict
-  const existing = await checkNameConflict(simulationName);
-  if (existing) {
-    throw new MiravoError(
-      `Simulation "${simulationName}" is already running (PID ${existing.pid}).`,
-      `Stop it first: miravo stop ${simulationName}`,
-    );
-  }
-
-  // 2. Check port conflicts
-  const ports = new Map<string, number>();
-  ports.set("admin", adminPort);
-  if (opts.mqttEnabled && opts.mqttEmbedded && opts.mqttPort !== undefined) {
-    ports.set("mqtt", opts.mqttPort);
-  }
-  if (opts.opcuaEnabled && opts.opcuaPort !== undefined) ports.set("opcua", opts.opcuaPort);
-  if (opts.modbusEnabled && opts.modbusPort !== undefined) ports.set("modbus", opts.modbusPort);
-
-  const conflicts = await checkPortConflicts(ports);
-  if (conflicts.length > 0) {
-    throw new MiravoError(
-      conflicts[0] ?? "Port conflict detected.",
-      "Use different port options or stop the conflicting simulation.",
-    );
-  }
-
-  // 3. Generate run ID and rebuild args
-  const runId = crypto.randomUUID();
-  const childArgs = rebuildArgsForDetach(opts);
-
-  // 4. Spawn child process
-  controlLog.info(`Starting simulation "${simulationName}" in background...`);
-  const proc = Bun.spawn({
-    cmd: [process.execPath, ...childArgs],
-    stdin: "ignore",
-    stdout: "ignore",
-    stderr: "ignore",
-    env: {
-      ...process.env,
-      MIRAVO_DAEMON_RUN_ID: runId,
-    },
-  });
-  proc.unref();
-
-  // 5. Poll for readiness
-  const adminUrl = `http://${adminHost}:${adminPort}`;
-  const ready = await pollReadiness(proc.pid, adminUrl, runId, 10, 1_000);
-
-  if (!ready) {
-    // Kill child if still alive
-    if (isPidAlive(proc.pid)) {
-      try {
-        process.kill(proc.pid, "SIGKILL");
-      } catch {
-        // Ignore kill errors
-      }
-    }
-
-    throw new MiravoError(
-      `Simulation "${simulationName}" failed to start within the readiness timeout.`,
-      "Check template and port availability. Run without -d to see full output.",
-    );
-  }
-
-  // 6. Write registry entry
-  const adapters: DaemonRegistryEntry["adapters"] = {};
-  if (opts.mqttEnabled) {
-    const mqttPort = opts.mqttPort ?? DEFAULT_MQTT_PORT;
-    adapters["mqtt"] = { port: mqttPort, host: opts.mqttHost ?? "127.0.0.1" };
-  }
-  if (opts.opcuaEnabled) {
-    const opcuaPort = opts.opcuaPort ?? DEFAULT_OPCUA_PORT;
-    adapters["opcua"] = { port: opcuaPort, host: opts.opcuaHost ?? "0.0.0.0" };
-  }
-  if (opts.modbusEnabled) {
-    const modbusPort = opts.modbusPort ?? DEFAULT_MODBUS_PORT;
-    adapters["modbus"] = { port: modbusPort, host: opts.modbusHost ?? "0.0.0.0" };
-  }
-
-  const entry: DaemonRegistryEntry = {
-    name: simulationName,
-    pid: proc.pid,
-    adminPort,
-    adminHost,
-    adapters,
-    templatePath: resolve(opts.templatePath),
-    startedAt: new Date().toISOString(),
-    seed: opts.seed,
-    runId,
-  };
-  try {
-    await writeEntry(entry);
-  } catch (err) {
-    // Registry write failed — kill the orphan child so it doesn't run invisible
-    // to miravo ps/stop/rm.
-    try {
-      process.kill(proc.pid, "SIGKILL");
-    } catch {
-      // Process may have already exited
-    }
-    throw err;
-  }
-  await releaseLock();
-
-  // 7. Print detach summary
-  printDetachSummary(entry);
-  process.exit(0);
-}
-
-function rebuildArgsForDetach(opts: DetachOptions): string[] {
-  // Start from the original argv, filtering out -d/--detach
-  const originalArgs = process.argv.slice(1); // skip bun/node executable
-  const filtered: string[] = [];
-  let hasName = false;
-  let hasSeed = false;
-
-  for (let i = 0; i < originalArgs.length; i++) {
-    const arg = originalArgs[i];
-    if (arg === undefined) continue;
-    if (arg === "-d" || arg === "--detach") continue;
-    if (arg === "-n" || arg === "--name") hasName = true;
-    if (arg === "--seed") hasSeed = true;
-    filtered.push(arg);
-  }
-
-  // Inject --name if not explicitly passed (ensures child uses same resolved name)
-  if (!hasName) {
-    filtered.push("--name", opts.simulationName);
-  }
-  // Inject --seed to freeze the seed (so child reproduces the same simulation)
-  if (!hasSeed) {
-    filtered.push("--seed", String(opts.seed));
-  }
-
-  return filtered;
-}
-
-async function pollReadiness(
-  pid: number,
-  adminUrl: string,
-  runId: string,
-  maxRetries: number,
-  intervalMs: number,
-): Promise<boolean> {
-  for (let attempt = 0; attempt < maxRetries; attempt++) {
-    await Bun.sleep(intervalMs);
-
-    if (!isPidAlive(pid)) return false;
-
-    try {
-      // Use /readyz to verify identity via runId. Accept any status (not just "ok")
-      // so external-MQTT daemons with slow broker reconnect can still start.
-      const response = await fetch(`${adminUrl}/readyz`, {
-        signal: AbortSignal.timeout(2_000),
-      });
-      const body = (await response.json()) as Record<string, unknown>;
-      if (body["runId"] === runId) return true;
-    } catch {
-      // Not ready yet — retry
-    }
-  }
-  return false;
-}
-
-function printDetachSummary(entry: DaemonRegistryEntry): void {
-  const admin = `http://${displayHost(entry.adminHost)}:${entry.adminPort}`;
-  const lines = [
-    `Simulation "${entry.name}" started in background (PID ${entry.pid})`,
-    "",
-    `  Console   ${admin}`,
-  ];
-
-  for (const [name, adapter] of Object.entries(entry.adapters) as [
-    string,
-    { port: number; host: string },
-  ][]) {
-    const host = displayHost(adapter.host);
-    if (name === "mqtt") {
-      lines.push(`  MQTT      mqtt://${host}:${adapter.port}`);
-    } else if (name === "opcua") {
-      lines.push(`  OPC UA    opc.tcp://${host}:${adapter.port}`);
-    } else if (name === "modbus") {
-      lines.push(`  Modbus    modbus://${host}:${adapter.port}`);
-    } else {
-      lines.push(`  ${name}      ${host}:${adapter.port}`);
-    }
-  }
-
-  lines.push("");
-  lines.push(`  Use ${colors.cyan(`miravo logs ${entry.name}`)} to view events`);
-  lines.push(`  Use ${colors.cyan(`miravo stop ${entry.name}`)} to stop`);
-
-  writeOutput(lines.join("\n"));
-}
-
-// ---------------------------------------------------------------------------
-// Step 1: Template resolution
-// ---------------------------------------------------------------------------
-
-async function peekStateTemplatePath(simulationName: string): Promise<string | undefined> {
-  const stateDir = `${resolveMiravoHome()}/state`;
-  const file = Bun.file(`${stateDir}/${simulationName}.json`);
-  if (!(await file.exists())) return undefined;
-  try {
-    const parsed = JSON.parse(await file.text()) as unknown;
-    const result = PersistedStateSchema.safeParse(parsed);
-    if (!result.success) return undefined;
-    return result.data.templateRuns.find((r) => r.templatePath.trim().length > 0)?.templatePath;
-  } catch {
-    return undefined;
-  }
-}
-
-async function peekSingleStateTemplatePath(): Promise<string | undefined> {
-  const stateDir = `${resolveMiravoHome()}/state`;
-  let bestTemplatePath: string | undefined;
-  let bestSavedAt = "";
-  try {
-    const glob = new Glob("*.json");
-    for await (const file of glob.scan({ cwd: stateDir, onlyFiles: true })) {
-      try {
-        const parsed = JSON.parse(await Bun.file(`${stateDir}/${file}`).text()) as unknown;
-        const result = PersistedStateSchema.safeParse(parsed);
-        if (!result.success) continue;
-        const templatePath = result.data.templateRuns.find(
-          (r) => r.templatePath.trim().length > 0,
-        )?.templatePath;
-        if (!templatePath) continue;
-        if (result.data.savedAt > bestSavedAt) {
-          bestSavedAt = result.data.savedAt;
-          bestTemplatePath = templatePath;
-        }
-      } catch {}
-    }
-  } catch {
-    return undefined; // state dir doesn't exist yet (first-ever run)
-  }
-  return bestTemplatePath;
-}
-
-async function resolveTemplatePath(
-  templateOption: string | undefined,
-  catalog: ContentCatalog,
-): Promise<string> {
-  // 1. Explicit --template identifier or path
-  if (templateOption) {
-    return resolveTemplateIdentifier(templateOption, catalog);
-  }
-
-  // 2. Auto-discover local templates from content dir (if configured) and CWD
-  const discovered = await discoverPreferredLocalTemplates(catalog);
-  if (discovered.length === 1) {
-    const first = discovered[0];
-    if (first !== undefined) {
-      configLog.info(`Found template: ${first.name} (${first.path})`);
-      return first.path;
-    }
-  }
-  if (discovered.length > 1) {
-    if (!process.stdout.isTTY || !process.stdin.isTTY) {
-      const names = discovered.map((t) => t.name).join(", ");
-      throw new MiravoError(
-        `Found ${discovered.length} templates: ${names}.`,
-        "Use '--template <name|path>' to specify which template to use.",
-      );
-    }
-    const first = discovered[0];
-    if (first !== undefined) {
-      configLog.warn(
-        `Found ${discovered.length} templates: ${discovered.map((t) => t.name).join(", ")}. Using ${first.name}. Use '--template <name|path>' to specify.`,
-      );
-      return first.path;
-    }
-  }
-
-  // 3. Fall back to built-in templates
-  const builtinTemplateDir = catalog.getBuiltinTemplatesDir();
-  let builtinTemplates: readonly DiscoveredTemplate[] = [];
-  try {
-    const discovered = await discoverTemplates(builtinTemplateDir);
-    // Exclude stress/benchmark templates from built-in list (same as standalone binaries).
-    builtinTemplates = discovered.filter((t) => !isStressBenchmarkTemplate(t.id));
-  } catch {
-    // Builtin dir may not exist in edge cases (e.g. standalone binary extraction failure)
-  }
-  if (builtinTemplates.length > 0) {
-    if (process.stdout.isTTY && process.stdin.isTTY) {
-      return pickBuiltinTemplate(builtinTemplates);
-    }
-    const selected = selectDefaultBuiltinTemplate(builtinTemplates);
-    if (selected !== undefined) {
-      configLog.info(`No template specified. Using built-in "${selected.name}".`);
-      configLog.info(
-        "Run 'miravo templates list' to see all options, or use --template <name|path>.",
-      );
-      return selected.path;
-    }
-  }
-
-  // 4. Nothing available
-  throw new ConfigNotFoundError(
-    "No template found. Use 'miravo templates list' to find built-ins or pass 'miravo start --template <name|path>'.",
-  );
-}
-
-async function pickBuiltinTemplate(templates: readonly DiscoveredTemplate[]): Promise<string> {
-  configLog.info("No template found in current directory.\n");
-
-  const choice = await select({
-    message: "Choose a built-in template to get started:",
-    options: buildBuiltinTemplateChoices(templates),
-    maxItems: 9,
-  });
-
-  if (isCancel(choice)) {
-    process.exit(0);
-  }
-
-  configLog.info("Tip: use --template <id> to skip this prompt next time.");
-
-  return choice as string;
-}
-
-export function buildBuiltinTemplateChoices(
-  templates: readonly DiscoveredTemplate[],
-): Array<ClackOption<string>> {
-  const groupedTemplates = groupTemplatesByCategory(sortTemplatesByCategoryAndName(templates));
-  const choices: ClackOption<string>[] = [];
-
-  for (const group of groupedTemplates) {
-    choices.push({
-      value: `__header__${group.category}`,
-      label: group.category,
-      hint: `${group.templates.length} templates`,
-      disabled: true,
-    });
-
-    for (const [index, template] of group.templates.entries()) {
-      const isLast = index === group.templates.length - 1;
-      const branch = isLast ? "\u2514\u2500" : "\u251C\u2500";
-      const label = `  ${branch} ${template.name}`;
-      const hintPrefix = template.description ?? template.id;
-      choices.push({
-        value: template.path,
-        label,
-        hint: `${hintPrefix} \u00B7 ${template.uniqueModelCount} models \u00B7 ${template.totalTwinCount} twins`,
-      });
-    }
-  }
-
-  return choices;
-}
-
-function selectDefaultBuiltinTemplate(
-  templates: readonly DiscoveredTemplate[],
-): DiscoveredTemplate | undefined {
-  const preferredFilename = "smart-factory.miravo.yaml";
-  return (
-    templates.find((template) => basename(template.path) === preferredFilename) ?? templates[0]
-  );
-}
-
-// ---------------------------------------------------------------------------
-// Step 2: Load and validate
-// ---------------------------------------------------------------------------
-
-async function loadAndValidateTemplate(
-  templatePath: string,
-  options: StartOptions,
-  catalog: ContentCatalog,
-): Promise<{
-  template: MiravoTemplate;
-  models: Map<string, TwinModel>;
-  seed: number;
-  seedExplicit: boolean;
-}> {
-  const template = await loadTemplate(templatePath);
-
-  // Build model search paths from catalog
-  const catalogSearchPaths = catalog.getTemplateValidationSearchPaths(templatePath);
-  const searchPaths = [...catalogSearchPaths];
-  if (options.modelsDir) {
-    // Insert after template dir but before other paths
-    searchPaths.splice(1, 0, resolve(options.modelsDir));
-  }
-  const uniqueSearchPaths = [...new Set(searchPaths.map((path) => resolve(path)))];
-
-  // Cross-validate
-  const validation = await validateFullTemplate(templatePath, uniqueSearchPaths);
-  for (const issue of validation.issues) {
-    if (issue.severity === "error") {
-      configLog.error(`${issue.message}\n  Fix: ${issue.fix}`);
-    } else {
-      configLog.warn(issue.message);
-    }
-  }
-  if (!validation.valid) {
-    throw new ConfigValidationError({
-      message: "Template validation failed. See errors above.",
-      fix: "Fix the reported issues and try again.",
-      filePath: templatePath,
-    });
-  }
-
-  // Build inline models map
-  const models = new Map<string, TwinModel>();
-  if (template.models) {
-    for (const inlineModel of template.models) {
-      models.set(inlineModel.model.name, inlineModel);
-    }
-  }
-
-  // Resolve and load all referenced models not already inline
-  const referencedModelNames = collectReferencedModels(template);
-
-  for (const modelName of referencedModelNames) {
-    if (models.has(modelName)) continue;
-    const modelPath = await resolveModelPath(modelName, uniqueSearchPaths);
-    const model = await loadTwinModel(modelPath);
-    models.set(modelName, model);
-  }
-
-  // Resolve seed: CLI flag > config setting > random
-  const configSeed = template.settings?.seed;
-  const cliSeed = options.seed;
-  const seedExplicit = cliSeed !== undefined || configSeed !== undefined;
-  const seed = cliSeed ?? configSeed ?? Date.now();
-
-  return { template, models, seed, seedExplicit };
-}
-
-export function resolveSimulationName(input: {
-  readonly template: MiravoTemplate;
-  readonly cliName?: string;
-  readonly envName?: string;
-}): string {
-  const { template, cliName, envName } = input;
-
-  const nameFromNamespace = (): string | undefined => {
-    const namespace = template.namespace;
-    if (!namespace) return undefined;
-    if ("enterprise" in namespace) {
-      return `${namespace.enterprise}-${namespace.site}`.toLowerCase();
-    }
-    return namespace.prefix.toLowerCase();
-  };
-
-  const rawName = cliName ?? envName ?? nameFromNamespace();
-  if (!rawName) {
-    throw new ConfigValidationError({
-      message: "Template has no namespace.",
-      fix: "Provide a simulation name via --name or MIRAVO_NAME.",
-    });
-  }
-
-  const parsed = SimulationNameSchema.safeParse(rawName);
-  if (!parsed.success) {
-    throw new ConfigValidationError({
-      message: `Invalid simulation name "${rawName}".`,
-      fix: "Use lowercase letters, numbers, and hyphens only (for example: north-plant).",
-    });
-  }
-
-  return parsed.data;
-}
-
-// ---------------------------------------------------------------------------
-// Step 4: Engine creation
-// ---------------------------------------------------------------------------
-
-function createAndPopulateEngine(
-  template: MiravoTemplate,
-  models: Map<string, TwinModel>,
-  catalog: ContentCatalog,
-  seed: number,
-  options: StartOptions,
-  templatePath: string,
-  simulationName: string,
-): Engine {
-  const tickIntervalMs =
-    options.tick ?? template.settings?.tick_interval_ms ?? DEFAULT_TICK_INTERVAL_MS;
-  const timeMultiplier =
-    options.speed ?? template.settings?.time_multiplier ?? DEFAULT_TIME_MULTIPLIER;
-  const overrunThresholdMultiplier = template.settings?.overrun_threshold_multiplier;
-  const searchPaths = catalog.getTemplateValidationSearchPaths(templatePath);
-
-  let engine!: Engine;
-  engine = createEngine({
-    simulationName,
-    seed,
-    tickIntervalMs,
-    timeMultiplier,
-    overrunThresholdMultiplier,
-    templateMetadata: {
-      name: template.name,
-      path: templatePath,
-    },
-    beforeRun: async ({ restoredFromPersistence }) => {
-      const protocolBootPlans = resolveProtocolBootPlans({
-        options,
-        optionSources: {
-          mqtt: getCommandOptionSource(options.command, "mqtt"),
-          opcua: getCommandOptionSource(options.command, "opcua"),
-          mqttPort: getCommandOptionSource(options.command, "mqttPort"),
-          mqttHost: getCommandOptionSource(options.command, "mqttHost"),
-          mqttMode: getCommandOptionSource(options.command, "mqttMode"),
-          mqttUrl: getCommandOptionSource(options.command, "mqttUrl"),
-          mqttUsername: getCommandOptionSource(options.command, "mqttUsername"),
-          mqttPassword: getCommandOptionSource(options.command, "mqttPassword"),
-          opcuaPort: getCommandOptionSource(options.command, "opcuaPort"),
-          opcuaHost: getCommandOptionSource(options.command, "opcuaHost"),
-          modbus: getCommandOptionSource(options.command, "modbus"),
-          modbusPort: getCommandOptionSource(options.command, "modbusPort"),
-          modbusHost: getCommandOptionSource(options.command, "modbusHost"),
-        },
-        restoredFromPersistence,
-      });
-
-      for (const plan of protocolBootPlans) {
-        await reconcileProtocolBootPlan(engine, plan);
-      }
-    },
-    persistence: {
-      enabled: true,
-      resetOnStart: options.resetState ?? false,
-      ensureModelRegistered: (modelName) =>
-        registerModelFromSearchPaths(engine.runtime, modelName, searchPaths),
-      loadTemplateModels: (persistedTemplatePath) => {
-        loadTemplateModels(catalog, persistedTemplatePath, engine.runtime);
-      },
-    },
-  });
-
-  // Register all models
-  for (const [, model] of models) {
-    engine.runtime.registerModel(model);
-  }
-
-  // Spawn instances from template with boot-time run ID
-  const bootRunId = 1;
-  const allInstanceIds: string[] = [];
-
-  forEachTwin(template, (area, line, twin) => {
-    const unsBasePath = buildUNSBasePath(template, area.name, line.name);
-    const spawned = engine.runtime.spawn(twin.model, twin.count, {
-      variation: twin.variation,
-      unsBasePath,
-      ...(twin.parameters !== undefined ? { parameterOverrides: twin.parameters } : {}),
-      ...(twin.starting_hours !== undefined ? { startingHours: twin.starting_hours } : {}),
-      templateRunId: bootRunId,
-    });
-    for (const node of spawned) {
-      allInstanceIds.push(node.id);
-    }
-  });
-
-  // Register boot-time template as a template run for persistence/unload support
-  engine.registerTemplateRun({
-    templateRunId: bootRunId,
-    templateName: template.name,
-    templatePath,
-    prefix: "boot",
-    instanceIds: allInstanceIds,
-    models: [...models.keys()],
-  });
-
-  return engine;
-}
-
-// ---------------------------------------------------------------------------
-// Runtime template loader (for loadTemplate command from console/API)
-// ---------------------------------------------------------------------------
-
-interface CachedTemplate {
-  readonly id: string;
-  readonly name: string;
-  readonly path: string;
-}
-
-interface TemplateCacheResult {
-  readonly pathCache: Map<string, CachedTemplate>;
-  readonly catalog: readonly CatalogTemplate[];
-}
-
-/**
- * Discover templates once and build both the path lookup cache (for runtime
- * template loading) and the catalog (for the REST API) in a single pass.
- * All data comes from discovery metadata — no additional file I/O.
- */
-async function buildTemplateCacheAndCatalog(
-  contentCatalog: ContentCatalog,
-): Promise<TemplateCacheResult> {
-  const pathCache = new Map<string, CachedTemplate>();
-  const catalogEntries: CatalogTemplate[] = [];
-  const discovered = await discoverTemplates(contentCatalog.getBuiltinTemplatesDir());
-
-  for (const t of discovered) {
-    const entry: CachedTemplate = { id: t.id, name: t.name, path: t.path };
-    pathCache.set(t.id, entry);
-    pathCache.set(t.name, entry);
-
-    catalogEntries.push({
-      id: t.id,
-      name: t.name,
-      description: t.description ?? null,
-      category: "Industrial",
-      models: t.modelNames,
-      instanceCount: t.totalTwinCount,
-      memberCount: 0,
-      source: "builtin",
-    });
-  }
-
-  return { pathCache, catalog: catalogEntries };
-}
-
-function createRuntimeTemplateLoader(
-  catalog: ContentCatalog,
-  templatePathCache: Map<string, CachedTemplate>,
-): (templatePath: string, count: number, runId: number, runtime: TwinRuntime) => TemplateRun {
-  return (templateIdentifier, count, runId, runtime) => {
-    // Resolve template path from pre-built cache or as a file path
-    let templatePath: string;
-    let slugName: string;
-    if (isTemplatePathLike(templateIdentifier)) {
-      templatePath = resolve(templateIdentifier);
-      slugName = basename(templatePath).replace(/\.miravo\.yaml$/, "");
-    } else {
-      const cached = templatePathCache.get(templateIdentifier);
-      if (!cached) {
-        const ids = [...new Set([...templatePathCache.values()].map((e) => e.id))];
-        throw new MiravoError(
-          `Template "${templateIdentifier}" not found.`,
-          `Available templates: ${ids.join(", ") || "(none)"}`,
-        );
-      }
-      templatePath = cached.path;
-      slugName = cached.id;
-    }
-
-    const template = loadTemplateSync(templatePath);
-    const referencedModels = registerTemplateModels(catalog, templatePath, template, runtime);
-
-    // Spawn instances with auto-prefix using kebab-case slug
-    const prefix = `${slugName}-${runId}`;
-    const allInstanceIds: string[] = [];
-
-    for (let c = 0; c < count; c++) {
-      const runPrefix = count > 1 ? `${prefix}-${c + 1}` : prefix;
-      forEachTwin(template, (area, line, twin) => {
-        const unsBasePath = `${runPrefix}/${buildUNSBasePath(template, area.name, line.name)}`;
-        const spawned = runtime.spawn(twin.model, twin.count, {
-          variation: twin.variation,
-          unsBasePath,
-          ...(twin.parameters !== undefined ? { parameterOverrides: twin.parameters } : {}),
-          ...(twin.starting_hours !== undefined ? { startingHours: twin.starting_hours } : {}),
-          templateRunId: runId,
-        });
-        for (const node of spawned) {
-          allInstanceIds.push(node.id);
-        }
-      });
-    }
-
-    return {
-      templateRunId: runId,
-      templateName: template.name,
-      templatePath,
-      prefix,
-      instanceIds: allInstanceIds,
-      models: [...referencedModels],
-    };
-  };
-}
-
-function loadTemplateSync(templatePath: string): MiravoTemplate {
-  try {
-    return MiravoTemplateSchema.parse(parseYAML(readFileSync(templatePath, "utf-8")));
-  } catch (err) {
-    throw new MiravoError(
-      `Failed to load template "${templatePath}".`,
-      err instanceof Error ? err.message : "Check that the file is valid YAML.",
-    );
-  }
-}
-
-function registerModelFromSearchPaths(
-  runtime: TwinRuntime,
-  modelName: string,
-  searchPaths: readonly string[],
-): void {
-  if (runtime.getModel(modelName)) {
-    return;
-  }
-
-  const { path: modelPath, content: modelContent } = loadModelSync(modelName, searchPaths);
-  try {
-    const model = TwinModelSchema.parse(parseYAML(modelContent));
-    runtime.registerModel(model);
-  } catch (err) {
-    throw new MiravoError(
-      `Failed to load model "${modelName}" from "${modelPath}".`,
-      err instanceof Error ? err.message : "Check that the model file is valid YAML.",
-    );
-  }
-}
-
-function loadTemplateModels(
-  catalog: ContentCatalog,
-  templatePath: string,
-  runtime: TwinRuntime,
-): readonly string[] {
-  const template = loadTemplateSync(templatePath);
-  return registerTemplateModels(catalog, templatePath, template, runtime);
-}
-
-function registerTemplateModels(
-  catalog: ContentCatalog,
-  templatePath: string,
-  template: MiravoTemplate,
-  runtime: TwinRuntime,
-): readonly string[] {
-  const referencedModels = collectReferencedModels(template);
-  const searchPaths = catalog.getTemplateValidationSearchPaths(templatePath);
-  for (const modelName of referencedModels) {
-    registerModelFromSearchPaths(runtime, modelName, searchPaths);
-  }
-  return [...referencedModels];
-}
-
-function loadModelSync(
-  modelName: string,
-  searchPaths: readonly string[],
-): { path: string; content: string } {
-  for (const dir of searchPaths) {
-    const candidate = resolve(dir, `${modelName}${TWIN_FILE_EXTENSION}`);
-    try {
-      return { path: candidate, content: readFileSync(candidate, "utf-8") };
-    } catch {
-      // File doesn't exist or can't be read — try next path
-    }
-  }
-  throw new MiravoError(
-    `Model "${modelName}" not found in search paths.`,
-    `Searched: ${searchPaths.join(", ")}. Ensure the model file exists as "${modelName}${TWIN_FILE_EXTENSION}".`,
-  );
-}
-
-// ---------------------------------------------------------------------------
-// Step 5: Adapter default config builders
-// ---------------------------------------------------------------------------
-
-function buildMQTTDefaultConfig(
-  template: MiravoTemplate,
-  portOverride: number | undefined,
-  mqttOverrides: MqttRunOverrides,
-  simulationName: string,
-): Record<string, unknown> {
-  const mqttConfig = template.protocols?.mqtt;
-  const port = portOverride ?? mqttConfig?.port ?? DEFAULT_MQTT_PORT;
-  let embedded = mqttConfig?.embedded ?? true;
-  let external = mqttConfig?.external;
-  let host = "127.0.0.1";
-  let username = mqttConfig?.username;
-  let password = mqttConfig?.password;
-  const modeOverride = mqttOverrides.mode;
-  if (modeOverride !== undefined) {
-    embedded = modeOverride === "embedded";
-    if (embedded) {
-      external = undefined;
-      username = undefined;
-      password = undefined;
-    }
-  }
-  if (mqttOverrides.url !== undefined) external = mqttOverrides.url;
-  if (mqttOverrides.host !== undefined) host = mqttOverrides.host;
-  if (mqttOverrides.username !== undefined) username = mqttOverrides.username;
-  if (mqttOverrides.password !== undefined) password = mqttOverrides.password;
-
-  if (embedded && (external || username || password)) {
-    throw new ConfigValidationError({
-      message: "Embedded MQTT mode cannot be combined with external MQTT URL or credentials.",
-      fix: "Use --mqtt-mode external for external broker settings, or remove external MQTT overrides.",
-    });
-  }
-  if (!embedded && !external) {
-    throw new ConfigValidationError({
-      message: "MQTT mode is external but no broker URL was provided.",
-      fix: "Set protocols.mqtt.external in template or pass --mqtt-url / MIRAVO_MQTT_URL.",
-    });
-  }
-  if (password && !username) {
-    throw new ConfigValidationError({
-      message: "MQTT password was provided without username.",
-      fix: "Provide --mqtt-username / MIRAVO_MQTT_USERNAME when setting a password.",
-    });
-  }
-
-  const drainBudget = mqttOverrides.drainBudget ?? mqttConfig?.drain_budget;
-  const batchSize = mqttOverrides.batchSize ?? mqttConfig?.batch_size;
-  const brokerConcurrency = mqttOverrides.brokerConcurrency ?? mqttConfig?.broker_concurrency;
-
-  return {
-    name: "mqtt",
-    enabled: true,
-    simulationName,
-    embedded,
-    port,
-    host,
-    retain: mqttConfig?.retain ?? false,
-    ...(external !== undefined ? { external } : {}),
-    ...(username !== undefined ? { username } : {}),
-    ...(password !== undefined ? { password } : {}),
-    ...(mqttConfig?.reconnect !== undefined ? { reconnect: mqttConfig.reconnect } : {}),
-    ...(mqttConfig?.rbe !== undefined ? { rbe: mqttConfig.rbe } : {}),
-    ...(mqttConfig?.metadata !== undefined ? { metadata: mqttConfig.metadata } : {}),
-    ...(drainBudget !== undefined ? { drain_budget: drainBudget } : {}),
-    ...(batchSize !== undefined ? { batch_size: batchSize } : {}),
-    ...(brokerConcurrency !== undefined ? { broker_concurrency: brokerConcurrency } : {}),
-  };
-}
-
-function buildOPCUADefaultConfig(
-  template: MiravoTemplate,
-  portOverride: number | undefined,
-  hostOverride: string | undefined,
-  simulationName: string,
-  writeBudgetOverride?: number,
-): Record<string, unknown> {
-  const opcuaConfig = template.protocols?.opcua;
-  const port = portOverride ?? opcuaConfig?.port ?? DEFAULT_OPCUA_PORT;
-  const host = hostOverride ?? opcuaConfig?.host ?? "0.0.0.0";
-  const writeBudget = writeBudgetOverride ?? opcuaConfig?.write_budget;
-
-  return {
-    name: "opcua",
-    enabled: true,
-    port,
-    host,
-    security: opcuaConfig?.security ?? "none",
-    simulationName,
-    ...(opcuaConfig?.buildInfo ? { buildInfo: opcuaConfig.buildInfo } : {}),
-    ...(writeBudget !== undefined ? { write_budget: writeBudget } : {}),
-  };
-}
-
-/** Derive the MQTT endpoint string from a resolved adapter config. */
-function buildMQTTEndpoint(config: import("@miravo/shared").ProtocolConfig): string {
-  const cfg = config as Record<string, unknown>;
-  const port = cfg["port"] ?? DEFAULT_MQTT_PORT;
-  const embedded = cfg["embedded"] ?? true;
-  const external = cfg["external"] as string | undefined;
-  return embedded ? `mqtt://localhost:${port}` : (external as string);
-}
-
-/** Derive the OPC UA endpoint string from a resolved adapter config. */
-function buildOPCUAEndpoint(config: import("@miravo/shared").ProtocolConfig): string {
-  const cfg = config as Record<string, unknown>;
-  const port = cfg["port"] ?? DEFAULT_OPCUA_PORT;
-  const host = cfg["host"] ?? "0.0.0.0";
-  const displayHost = host === "0.0.0.0" ? "localhost" : host;
-  return `opc.tcp://${displayHost}:${port}`;
-}
-
-function buildModbusDefaultConfig(
-  template: MiravoTemplate,
-  portOverride: number | undefined,
-  hostOverride: string | undefined,
-): Record<string, unknown> {
-  const modbusConfig = template.protocols?.modbus;
-  const port = portOverride ?? modbusConfig?.port ?? DEFAULT_MODBUS_PORT;
-  const host = hostOverride ?? modbusConfig?.host ?? "0.0.0.0";
-  return { name: "modbus", enabled: true, port, host };
-}
-
-function buildModbusEndpoint(config: Record<string, unknown>): string {
-  const port = (config as { port?: number }).port ?? DEFAULT_MODBUS_PORT;
-  const host = (config as { host?: string }).host ?? "0.0.0.0";
-  return `modbus://${displayHost(String(host))}:${port}`;
-}
-
-// ---------------------------------------------------------------------------
-// Step 6: Startup banner
-// ---------------------------------------------------------------------------
-
-function printStartupBanner(
-  templatePath: string,
-  engine: Engine,
-  seed: number,
-  seedExplicit: boolean,
-  mqttEndpoint: string | null,
-  opcuaEndpoint: string | null,
-  modbusEndpoint: string | null,
-  simulationName: string,
-  runId: string,
-  adminEndpoint: string,
-): void {
-  const state = engine.getState();
-
-  // Build model summary: one model per line for readability
-  const modelLines = state.models.map(
-    (m) => `${colors.bold(m.name)} ${colors.dim(`(${m.memberCount} members)`)}`,
-  );
-  const modelCount = `${colors.bold(String(state.models.length))} ${colors.dim("models")}`;
-
-  const seedValue = seedExplicit
-    ? colors.bold(String(seed))
-    : `${colors.bold(String(seed))} ${colors.gray("(random — add seed to config to reproduce)")}`;
-
-  const mqttValue = mqttEndpoint ? colors.cyan(mqttEndpoint) : colors.dim("disabled");
-  const opcuaValue = opcuaEndpoint ? colors.cyan(opcuaEndpoint) : colors.dim("disabled");
-  const modbusValue = modbusEndpoint ? colors.cyan(modbusEndpoint) : colors.dim("disabled");
-
-  const allEntries: ReadonlyArray<readonly [string, string]> = [
-    [colors.dim("Simulation"), colors.bold(simulationName)],
-    [colors.dim("Run ID"), colors.bold(runId)],
-    [colors.dim("Template"), templatePath],
-    [colors.dim("Models"), modelCount],
-    [colors.dim("Instances"), colors.bold(String(state.instances.length))],
-    [colors.dim("MQTT"), mqttValue],
-    [colors.dim("OPC UA"), opcuaValue],
-    [colors.dim("Modbus"), modbusValue],
-    [colors.dim("Admin"), colors.cyan(adminEndpoint)],
-    [colors.dim("Tick interval"), colors.bold(`${state.config.tickIntervalMs}ms`)],
-    [colors.dim("Time multiplier"), colors.bold(`${state.config.timeMultiplier}x`)],
-    [colors.dim("Seed"), seedValue],
-  ];
-
-  const kvBlock = formatKeyValue(allEntries);
-
-  // Compute the value column offset used by formatKeyValue so model detail
-  // lines align with the value of the "Models" row.
-  const maxKeyWidth = Math.max(...allEntries.map(([key]) => stripAnsi(key).length));
-  const valueIndent = 4 + maxKeyWidth + 3; // "    " + key + ":" + padding(2) + " "
-
-  // Inject per-model detail lines right after the "Models" row
-  const kvLines = kvBlock.split("\n");
-  const modelsIdx = kvLines.findIndex((line) => stripAnsi(line).includes("Models:"));
-  if (modelsIdx !== -1 && modelLines.length > 0) {
-    const detailLines = modelLines.map((line) => `${"".padEnd(valueIndent)}${line}`);
-    kvLines.splice(modelsIdx + 1, 0, ...detailLines);
-  }
-  const content = kvLines.join("\n");
-
-  const header = `${colors.cyan(colors.bold("Miravo"))} ${colors.dim(`v${MIRAVO_VERSION}`)}`;
-
-  if (isPlain()) {
-    writeOutput(`${header}`);
-    writeOutput(content);
-    writeOutput();
-    engineLog.start("Press Ctrl+C to stop.");
-    return;
-  }
-
-  writeOutput(
-    box(content, {
-      title: header,
-      style: { borderColor: "cyan", borderStyle: "rounded" },
-    }),
-  );
-
-  engineLog.start("Press Ctrl+C to stop.");
-}
-
-function parseMqttModeOption(raw: string | undefined): MqttMode | undefined {
-  if (raw === undefined) {
-    return undefined;
-  }
-
-  if (raw === "embedded" || raw === "external") {
-    return raw;
-  }
-
-  throw new ConfigValidationError({
-    message: `Invalid MQTT mode "${raw}".`,
-    fix: "Use --mqtt-mode embedded|external or MIRAVO_MQTT_MODE=embedded|external.",
-  });
-}
-
-// ---------------------------------------------------------------------------
-// Step 7: Event subscriptions + periodic summary
-// ---------------------------------------------------------------------------
-
-function subscribeToEvents(engine: Engine, errorContextCounts: Map<string, number>): () => void {
-  const onLifecycle = (event: {
-    instanceId: string;
-    from: string;
-    to: string;
-    operatingHours: number;
-  }): void => {
-    lifecycleLog.info(
-      `${event.instanceId} ${event.from} ${colors.dim("\u2192")} ${event.to} ${colors.gray(`(${event.operatingHours.toFixed(0)}h)`)}`,
-    );
-  };
-
-  const onFaultTriggered = (event: { instanceId: string; fault: string }): void => {
-    faultLog.warn(`${event.instanceId} ${event.fault} triggered`);
-  };
-
-  const onFaultCleared = (event: { instanceId: string; fault: string }): void => {
-    faultLog.debug(`${event.instanceId} ${event.fault} cleared`);
-  };
-
-  const onWarn = (event: { message: string; context: string }): void => {
-    engineLog.debug(event.message, { context: event.context });
-  };
-
-  const onReset = (event: {
-    instanceCount: number;
-    templateRunCount: number;
-    clearPersistence: boolean;
-  }): void => {
-    const suffix = event.clearPersistence ? " · saved state cleared" : "";
-    engineLog.info(
-      `simulation reset · ${colors.bold(String(event.instanceCount))} instances · ${colors.bold(String(event.templateRunCount))} template runs${suffix}`,
-    );
-  };
-
-  const onError = (event: { context: string; error: Error }): void => {
-    incrementErrorContextCount(errorContextCounts, event.context);
-    engineLog.error(
-      "engine:error",
-      {
-        context: event.context,
-        errorName: event.error.name,
-        errorMessage: event.error.message,
-      },
-      event.error,
-    );
-  };
-
-  engine.bus.on("lifecycle:changed", onLifecycle);
-  engine.bus.on("fault:triggered", onFaultTriggered);
-  engine.bus.on("fault:cleared", onFaultCleared);
-  engine.bus.on("engine:warn", onWarn);
-  engine.bus.on("engine:error", onError);
-  engine.bus.on("engine:reset", onReset);
-
-  return () => {
-    engine.bus.off("lifecycle:changed", onLifecycle);
-    engine.bus.off("fault:triggered", onFaultTriggered);
-    engine.bus.off("fault:cleared", onFaultCleared);
-    engine.bus.off("engine:warn", onWarn);
-    engine.bus.off("engine:error", onError);
-    engine.bus.off("engine:reset", onReset);
-  };
-}
-
-export function normalizeErrorContext(raw: string): string {
-  return raw
-    .replace(/tick=\d+/g, "tick=*")
-    .replace(/instance="[^"]+"/g, 'instance="*"')
-    .replace(/model="[^"]+"/g, 'model="*"');
-}
-
-export function incrementErrorContextCount(counts: Map<string, number>, rawContext: string): void {
-  const normalizedContext = normalizeErrorContext(rawContext);
-  if (counts.has(normalizedContext)) {
-    counts.set(normalizedContext, (counts.get(normalizedContext) ?? 0) + 1);
-    return;
-  }
-
-  if (counts.size < MAX_ERROR_CONTEXT_KEYS) {
-    counts.set(normalizedContext, 1);
-    return;
-  }
-
-  counts.set(ERROR_CONTEXT_OVERFLOW, (counts.get(ERROR_CONTEXT_OVERFLOW) ?? 0) + 1);
-}
-
-function getCommandOptionSource(
-  command: Command | undefined,
-  optionName: ProtocolOptionSource,
-): string | undefined {
-  const maybeGetOptionValueSource = (
-    command as Command & { getOptionValueSource?: (key: string) => string | undefined }
-  )?.getOptionValueSource;
-  return maybeGetOptionValueSource?.call(command, optionName);
-}
-
-export function resolveProtocolBootPlans(input: {
-  readonly options: StartOptions & { readonly command?: Command | undefined };
-  readonly optionSources: Partial<Record<ProtocolOptionSource, string | undefined>>;
-  readonly restoredFromPersistence: boolean;
-}): readonly ProtocolBootPlan[] {
-  const mqttConfigExplicit = [
-    "mqttPort",
-    "mqttHost",
-    "mqttMode",
-    "mqttUrl",
-    "mqttUsername",
-    "mqttPassword",
-  ].some((option) => input.optionSources[option as ProtocolOptionSource] === "cli");
-
-  const opcuaConfigExplicit =
-    input.options.opcua === true &&
-    ["opcuaPort", "opcuaHost"].some(
-      (option) => input.optionSources[option as ProtocolOptionSource] === "cli",
-    );
-
-  const modbusConfigExplicit =
-    input.options.modbus === true &&
-    ["modbusPort", "modbusHost"].some(
-      (option) => input.optionSources[option as ProtocolOptionSource] === "cli",
-    );
-
-  return [
-    {
-      name: "mqtt",
-      shouldEnable: input.options.mqtt !== false,
-      overrideRestore:
-        !input.restoredFromPersistence ||
-        input.optionSources["mqtt"] === "cli" ||
-        mqttConfigExplicit,
-    },
-    {
-      name: "opcua",
-      shouldEnable: input.options.opcua === true,
-      overrideRestore:
-        !input.restoredFromPersistence ||
-        input.optionSources["opcua"] === "cli" ||
-        opcuaConfigExplicit,
-    },
-    {
-      name: "modbus",
-      shouldEnable: input.options.modbus === true,
-      overrideRestore:
-        !input.restoredFromPersistence ||
-        input.optionSources["modbus"] === "cli" ||
-        modbusConfigExplicit,
-    },
-  ];
-}
-
-export function resolveDetachAdapterConfigs(input: {
-  readonly template: MiravoTemplate;
-  readonly simulationName: string;
-  readonly mqtt: {
-    readonly enabled: boolean;
-    readonly portOverride: number | undefined;
-    readonly overrides: MqttRunOverrides;
-  };
-  readonly opcua: {
-    readonly enabled: boolean;
-    readonly portOverride: number | undefined;
-    readonly hostOverride: string | undefined;
-    readonly writeBudgetOverride: number | undefined;
-  };
-  readonly modbus: {
-    readonly enabled: boolean;
-    readonly portOverride: number | undefined;
-    readonly hostOverride: string | undefined;
-  };
-}): ResolvedDetachAdapterConfigs {
-  const mqttConfig = input.mqtt.enabled
-    ? buildMQTTDefaultConfig(
-        input.template,
-        input.mqtt.portOverride,
-        input.mqtt.overrides,
-        input.simulationName,
-      )
-    : null;
-  const opcuaConfig = input.opcua.enabled
-    ? buildOPCUADefaultConfig(
-        input.template,
-        input.opcua.portOverride,
-        input.opcua.hostOverride,
-        input.simulationName,
-        input.opcua.writeBudgetOverride,
-      )
-    : null;
-  const modbusConfig = input.modbus.enabled
-    ? buildModbusDefaultConfig(input.template, input.modbus.portOverride, input.modbus.hostOverride)
-    : null;
-
-  return {
-    mqtt: {
-      port: mqttConfig ? ((mqttConfig as { port?: number }).port ?? DEFAULT_MQTT_PORT) : undefined,
-      host: mqttConfig ? ((mqttConfig as { host?: string }).host ?? "127.0.0.1") : undefined,
-      embedded: mqttConfig ? ((mqttConfig as { embedded?: boolean }).embedded ?? true) : false,
-    },
-    opcua: {
-      port: opcuaConfig
-        ? ((opcuaConfig as { port?: number }).port ?? DEFAULT_OPCUA_PORT)
-        : undefined,
-      host: opcuaConfig ? ((opcuaConfig as { host?: string }).host ?? "0.0.0.0") : undefined,
-    },
-    modbus: {
-      port: modbusConfig
-        ? ((modbusConfig as { port?: number }).port ?? DEFAULT_MODBUS_PORT)
-        : undefined,
-      host: modbusConfig ? ((modbusConfig as { host?: string }).host ?? "0.0.0.0") : undefined,
-    },
-  };
-}
-
-async function reconcileProtocolBootPlan(engine: Engine, plan: ProtocolBootPlan): Promise<void> {
-  const adapter = engine.getAvailableAdapters().find((candidate) => candidate.name === plan.name);
-  const isEnabled = adapter?.enabled === true;
-
-  if (!plan.shouldEnable) {
-    if (!isEnabled || !plan.overrideRestore) {
-      return;
-    }
-
-    const result = await engine.disableAdapter(plan.name);
-    if (!result.success) {
-      throw new MiravoError(
-        result.message,
-        result.error ?? `Disable adapter "${plan.name}" manually and retry startup.`,
-      );
-    }
-    return;
-  }
-
-  if (plan.overrideRestore && isEnabled) {
-    const disableResult = await engine.disableAdapter(plan.name);
-    if (!disableResult.success) {
-      throw new MiravoError(
-        disableResult.message,
-        disableResult.error ?? `Disable adapter "${plan.name}" manually and retry startup.`,
-      );
-    }
-    if ((disableResult.data as { stopWarning?: boolean } | undefined)?.stopWarning === true) {
-      throw new MiravoError(
-        `Failed to safely reconfigure adapter "${plan.name}" during startup.`,
-        `The previous ${plan.name.toUpperCase()} adapter instance did not stop cleanly. Free the port or clear the persisted adapter state before retrying.`,
-      );
-    }
-  } else if (isEnabled) {
-    return;
-  }
-
-  const result = await engine.enableAdapter(plan.name);
-  if (!result.success) {
-    throw new MiravoError(
-      result.message,
-      result.error ?? `Check ${plan.name.toUpperCase()} configuration.`,
-    );
-  }
-
-  if (plan.name === "mqtt") {
-    mqttLog.ready(
-      `connected · broker: ${colors.cyan(String((result.data as Record<string, unknown>)?.["endpoint"] ?? ""))}`,
-    );
-    return;
-  }
-
-  if (plan.name === "modbus") {
-    modbusLog.ready(
-      `server ready · endpoint: ${colors.cyan(String((result.data as Record<string, unknown>)?.["endpoint"] ?? ""))}`,
-    );
-    return;
-  }
-
-  opcuaLog.ready(
-    `server ready · endpoint: ${colors.cyan(String((result.data as Record<string, unknown>)?.["endpoint"] ?? ""))}`,
-  );
-}
-
-function startPeriodicSummary(
-  engine: Engine,
-  intervalSeconds: number,
-): ReturnType<typeof setInterval> {
-  return setInterval(() => {
-    const metrics = engine.getMetrics();
-    printSummaryLine(metrics);
-  }, intervalSeconds * 1_000);
-}
-
-// ---------------------------------------------------------------------------
-// Step 3: Dry-run summary
-// ---------------------------------------------------------------------------
-
-function printDryRunSummary(
-  template: MiravoTemplate,
-  models: Map<string, TwinModel>,
-  seed: number,
-  seedExplicit: boolean,
-  templatePath: string,
-): void {
-  configLog.success("Dry-run validation passed.");
-
-  const seedValue = seedExplicit
-    ? colors.bold(String(seed))
-    : `${colors.bold(String(seed))} ${colors.gray("(random — add seed to config to reproduce)")}`;
-
-  const lines: string[] = [];
-
-  lines.push(
-    formatKeyValue([
-      [colors.dim("Template"), templatePath],
-      [colors.dim("Seed"), seedValue],
-    ]),
-  );
-
-  // Model table
-  const modelRows = [...models.values()].map((m) => ({
-    name: colors.cyan(m.model.name),
-    members: String(Object.keys(m.members).length),
-    faults: String(m.faults?.length ?? 0),
-    lifecycle: m.lifecycle ? `${m.lifecycle.stages.length} stages` : colors.dim("none"),
-  }));
-
-  if (modelRows.length > 0) {
-    lines.push("");
-    lines.push(`  ${colors.bold("Models:")}`);
-    lines.push(
-      formatTable(
-        {
-          name: colors.dim("Name"),
-          members: colors.dim("Members"),
-          faults: colors.dim("Faults"),
-          lifecycle: colors.dim("Lifecycle"),
-        },
-        modelRows,
-      ),
-    );
-  }
-
-  // Instance summary
-  let totalInstances = 0;
-  let totalMembers = 0;
-  forEachTwin(template, (_area, _line, twin) => {
-    totalInstances += twin.count;
-    const model = models.get(twin.model);
-    if (model) {
-      totalMembers += twin.count * Object.keys(model.members).length;
-    }
-  });
-
-  lines.push("");
-  lines.push(
-    formatKeyValue([
-      [colors.dim("Total instances"), colors.bold(String(totalInstances))],
-      [colors.dim("Total members"), colors.bold(String(totalMembers))],
-    ]),
-  );
-
-  if (isPlain()) {
-    writeOutput("Summary");
-    for (const line of lines) {
-      writeOutput(line);
-    }
-    writeOutput();
-    return;
-  }
-
-  writeOutput(
-    box(lines.join("\n"), {
-      title: " Summary ",
-      style: { borderColor: "cyan", borderStyle: "rounded" },
-    }),
-  );
-}