miravo 0.2.3 → 0.4.0

package/src/commands/start.ts

@@ -1,19 +1,27 @@
+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 } from "@miravo/core";
+import type { ContentCatalog, ControlPlane, Engine, TwinRuntime } from "@miravo/core";
 import {
   createControlPlane,
   createEngine,
   discoverTemplates,
   loadTemplate,
   loadTwinModel,
+  resolveMiravoHome,
   resolveModelPath,
   validateFullTemplate,
 } from "@miravo/core";
 import { MQTTAdapter } from "@miravo/mqtt";
 import { OPCUAAdapter } from "@miravo/opcua";
-import type { DiscoveredTemplate, MiravoTemplate, TwinModel } from "@miravo/shared";
+import type {
+  CatalogTemplate,
+  DiscoveredTemplate,
+  MiravoTemplate,
+  TemplateRun,
+  TwinModel,
+} from "@miravo/shared";
 import {
   ConfigNotFoundError,
   ConfigValidationError,
@@ -23,11 +31,26 @@ import {
   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,
@@ -44,8 +67,10 @@ import {
 import {
   createCatalog,
   discoverPreferredLocalTemplates,
+  isTemplatePathLike,
   resolveTemplateIdentifier,
 } from "../lib/template-locator.ts";
+import { buildUNSBasePath, collectReferencedModels, forEachTwin } from "../lib/template-utils.ts";
 import {
   clearRuntimeLogContext,
   configLog,
@@ -83,16 +108,76 @@ interface StartOptions {
   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";
+  readonly shouldEnable: boolean;
+  readonly overrideRestore: boolean;
 }
 
+type ProtocolOptionSource =
+  | "mqtt"
+  | "opcua"
+  | "mqttPort"
+  | "mqttHost"
+  | "mqttMode"
+  | "mqttUrl"
+  | "mqttUsername"
+  | "mqttPassword"
+  | "opcuaPort"
+  | "opcuaHost";
+
 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. 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;
@@ -105,11 +190,11 @@ const ERROR_CONTEXT_OVERFLOW = "__overflow__";
 export function registerStartCommand(program: Command): void {
   program
     .command("start")
-    .description("Start the simulation engine")
-    .option("-n, --name <name>", "Simulation name for control topics (env: MIRAVO_NAME)")
+    .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 identifier, display name, or .miravo.yaml path (env: MIRAVO_TEMPLATE)",
+      "-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)
@@ -139,14 +224,29 @@ export function registerStartCommand(program: Command): void {
       "Admin server port (default: 8080, env: MIRAVO_ADMIN_PORT)",
       parsePort,
     )
-    .option("-d, --dry-run", "Validate config and print summary without starting")
+    .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,
     )
-    .action(async (options: StartOptions) => {
-      await startAction(options);
+    .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 });
     });
 }
 
@@ -163,7 +263,16 @@ async function startAction(options: StartOptions): Promise<void> {
     const catalog = createCatalog();
 
     // Resolve env-var fallbacks for common options
-    const templateOption = options.template ?? Bun.env["MIRAVO_TEMPLATE"];
+    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
@@ -213,6 +322,15 @@ async function startAction(options: StartOptions): Promise<void> {
       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 } : {}),
@@ -223,6 +341,9 @@ async function startAction(options: StartOptions): Promise<void> {
         ...(mqttPassword !== undefined && mqttPassword.length > 0
           ? { password: mqttPassword }
           : {}),
+        ...(drainBudget !== undefined ? { drainBudget } : {}),
+        ...(batchSize !== undefined ? { batchSize } : {}),
+        ...(brokerConcurrency !== undefined ? { brokerConcurrency } : {}),
       };
       if (portOption === undefined && portEnv) {
         try {
@@ -245,6 +366,7 @@ async function startAction(options: StartOptions): Promise<void> {
     // 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) {
@@ -264,6 +386,10 @@ async function startAction(options: StartOptions): Promise<void> {
           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);
+      }
     }
 
     let adminPort = options.adminPort;
@@ -279,9 +405,35 @@ async function startAction(options: StartOptions): Promise<void> {
     }
     adminPort ??= 8080;
 
-    // Step 1: Resolve template path
-    const templatePath = await resolveTemplatePath(templateOption, catalog);
+    // 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(
@@ -303,7 +455,26 @@ async function startAction(options: StartOptions): Promise<void> {
       return;
     }
 
-    const runId = crypto.randomUUID();
+    // Step 3b: Detach check — spawn background process and exit
+    if (options.detach) {
+      await detachAction({
+        simulationName,
+        templatePath,
+        seed,
+        seedExplicit,
+        adminHost,
+        adminPort,
+        mqttPort: options.mqttPort,
+        mqttHost: options.mqttHost,
+        mqttEnabled,
+        opcuaPort,
+        opcuaHost,
+        opcuaEnabled,
+      });
+      return;
+    }
+
+    const runId = Bun.env["MIRAVO_DAEMON_RUN_ID"] ?? crypto.randomUUID();
     setRuntimeLogContext({ simulationName, runId });
     runtimeLogContextSet = true;
     controlLog.info(`Run ID: ${runId}`);
@@ -321,9 +492,39 @@ async function startAction(options: StartOptions): Promise<void> {
     });
 
     // Step 4: Create engine and populate
-    engine = createAndPopulateEngine(template, models, seed, options, templatePath, simulationName);
+    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();
@@ -350,51 +551,136 @@ async function startAction(options: StartOptions): Promise<void> {
 
     shutdown.addTask("cleanup", "CLI resources", stopCliResources);
 
-    // Step 5: Start MQTT adapter (unless --no-mqtt)
-    const mqttStartResult = mqttEnabled
-      ? await startMQTTAdapter(engine, template, portOption, mqttOverrides, simulationName)
-      : null;
-    const adapter = mqttStartResult?.adapter ?? null;
-
-    // Step 5a: Start OPC UA adapter (only when --opcua)
-    const opcuaResult = opcuaEnabled
-      ? await startOPCUAAdapter(engine, template, opcuaPort, opcuaHost, simulationName)
-      : null;
-
-    // Step 5b: Wire control plane
-    if (adapter) {
-      const transport = adapter.getControlTransport();
-      if (transport) {
-        controlPlane = createControlPlane({
-          simulationName,
-          engine,
-          transport,
-          bus: engine.bus,
-        });
-        controlPlane.start();
-        controlLog.info(`active on $miravo/${simulationName}/* topics`);
+    // 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,
+    );
+
+    // 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`);
     }
 
-    // Step 5c: Start admin HTTP server
-    engine.bus.on("tick:complete", onTickProgress);
+    // 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,
-        host: adminHost,
-        port: adminPort,
-        tickIntervalMs: engine.getState().config.tickIntervalMs,
-        mqttEnabled: adapter !== null,
-        isMqttConnected: () => (adapter ? adapter.getMetrics().connected : false),
-        opcuaEnabled: opcuaResult !== null,
-        isOpcuaConnected: () => (opcuaResult ? opcuaResult.adapter.getMetrics().connected : false),
-        getLastTickProgressAt: () => lastTickProgressAt,
+        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) {
-      tickProgressSubscribed = false;
-      engine.bus.off("tick:complete", onTickProgress);
       const message = error instanceof Error ? error.message : String(error);
       throw new MiravoError(
         `Admin server failed to start on ${adminHost}:${adminPort}: ${message}`,
@@ -402,27 +688,33 @@ async function startAction(options: StartOptions): Promise<void> {
       );
     }
 
-    // Step 6: Print startup banner
+    // 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;
     printStartupBanner(
       templatePath,
-      engine,
+      eng,
       seed,
       seedExplicit,
-      mqttStartResult?.endpoint ?? null,
-      opcuaResult?.endpoint ?? null,
+      mqttEndpoint,
+      opcuaEndpoint,
       simulationName,
       runId,
       adminServer.endpoint,
     );
 
-    // Step 7: Subscribe to events + periodic summary
-    const errorContextCounts = new Map<string, number>();
-    unsubscribeEvents = subscribeToEvents(engine, errorContextCounts);
-    shutdown.setErrorContextCounts(errorContextCounts);
-    const summaryInterval = options.summaryInterval ?? 5;
-    summaryTimer = startPeriodicSummary(engine, summaryInterval);
+    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)");
+    }
 
-    engine.start();
     shutdown.markRunning();
     engineLog.success("Simulation started.");
     await shutdownRequested;
@@ -449,10 +741,277 @@ async function startAction(options: StartOptions): Promise<void> {
   }
 }
 
+// ---------------------------------------------------------------------------
+// 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 mqttEnabled: boolean;
+  readonly opcuaPort: number | undefined;
+  readonly opcuaHost: string | undefined;
+  readonly opcuaEnabled: boolean;
+}
+
+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.mqttPort) ports.set("mqtt", opts.mqttPort);
+  if (opts.mqttEnabled && !opts.mqttPort) ports.set("mqtt", DEFAULT_MQTT_PORT);
+  if (opts.opcuaEnabled && opts.opcuaPort) ports.set("opcua", opts.opcuaPort);
+  if (opts.opcuaEnabled && !opts.opcuaPort) ports.set("opcua", DEFAULT_OPCUA_PORT);
+
+  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" };
+  }
+
+  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 {
+      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,
@@ -626,14 +1185,7 @@ async function loadAndValidateTemplate(
   }
 
   // Resolve and load all referenced models not already inline
-  const referencedModelNames = new Set<string>();
-  for (const area of template.areas) {
-    for (const line of area.lines) {
-      for (const twin of line.twins) {
-        referencedModelNames.add(twin.model);
-      }
-    }
-  }
+  const referencedModelNames = collectReferencedModels(template);
 
   for (const modelName of referencedModelNames) {
     if (models.has(modelName)) continue;
@@ -693,6 +1245,7 @@ export function resolveSimulationName(input: {
 function createAndPopulateEngine(
   template: MiravoTemplate,
   models: Map<string, TwinModel>,
+  catalog: ContentCatalog,
   seed: number,
   options: StartOptions,
   templatePath: string,
@@ -703,8 +1256,10 @@ function createAndPopulateEngine(
   const timeMultiplier =
     options.speed ?? template.settings?.time_multiplier ?? DEFAULT_TIME_MULTIPLIER;
   const overrunThresholdMultiplier = template.settings?.overrun_threshold_multiplier;
+  const searchPaths = catalog.getTemplateValidationSearchPaths(templatePath);
 
-  const engine = createEngine({
+  let engine!: Engine;
+  engine = createEngine({
     simulationName,
     seed,
     tickIntervalMs,
@@ -714,6 +1269,37 @@ function createAndPopulateEngine(
       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"),
+        },
+        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
@@ -721,49 +1307,226 @@ function createAndPopulateEngine(
     engine.runtime.registerModel(model);
   }
 
-  // Spawn instances from template
-  for (const area of template.areas) {
-    for (const line of area.lines) {
-      for (const twin of line.twins) {
-        const unsBasePath = buildUNSBasePath(template, area.name, line.name);
+  // 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);
+    }
+  });
 
-        engine.runtime.spawn(twin.model, twin.count, {
+  // 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.",
+    );
   }
+}
 
-  return engine;
+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 buildUNSBasePath(template: MiravoTemplate, areaName: string, lineName: string): string {
-  const segments: string[] = [];
-  const ns = template.namespace;
-  if (ns !== undefined) {
-    if ("enterprise" in ns) {
-      segments.push(ns.enterprise, ns.site);
-    } else if ("prefix" in ns) {
-      segments.push(ns.prefix);
+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
     }
   }
-  segments.push(areaName, lineName);
-  return segments.join("/");
+  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: MQTT adapter
+// Step 5: Adapter default config builders
 // ---------------------------------------------------------------------------
 
-async function startMQTTAdapter(
-  engine: Engine,
+function buildMQTTDefaultConfig(
   template: MiravoTemplate,
   portOverride: number | undefined,
   mqttOverrides: MqttRunOverrides,
   simulationName: string,
-): Promise<{ adapter: MQTTAdapter; endpoint: string } | null> {
+): Record<string, unknown> {
   const mqttConfig = template.protocols?.mqtt;
   const port = portOverride ?? mqttConfig?.port ?? DEFAULT_MQTT_PORT;
   let embedded = mqttConfig?.embedded ?? true;
@@ -780,17 +1543,16 @@ async function startMQTTAdapter(
       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 (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({
@@ -798,12 +1560,6 @@ async function startMQTTAdapter(
       fix: "Set protocols.mqtt.external in template or pass --mqtt-url / MIRAVO_MQTT_URL.",
     });
   }
-  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 (password && !username) {
     throw new ConfigValidationError({
       message: "MQTT password was provided without username.",
@@ -811,92 +1567,70 @@ async function startMQTTAdapter(
     });
   }
 
-  if (!embedded && !external) {
-    mqttLog.warn("MQTT disabled — embedded is false with no external broker URL.");
-    return null;
-  }
-
-  const endpoint = embedded ? `mqtt://localhost:${port}` : (external as string);
-  mqttLog.debug(
-    `starting adapter · mode: ${embedded ? "embedded" : "external"} · endpoint: ${endpoint}`,
-  );
+  const drainBudget = mqttOverrides.drainBudget ?? mqttConfig?.drain_budget;
+  const batchSize = mqttOverrides.batchSize ?? mqttConfig?.batch_size;
+  const brokerConcurrency = mqttOverrides.brokerConcurrency ?? mqttConfig?.broker_concurrency;
 
-  const adapter = new MQTTAdapter(engine.bus);
-  try {
-    const resolvedConfig = {
-      name: "mqtt" as const,
-      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 } : {}),
-    };
-
-    await adapter.start(resolvedConfig);
-    engine.registerAdapter(adapter);
-    mqttLog.ready(`connected · broker: ${colors.cyan(endpoint)}`);
-    return { adapter, endpoint };
-  } catch (error) {
-    const message = error instanceof Error ? error.message : String(error);
-    const isPortConflict = message.includes("EADDRINUSE") || message.includes("in use");
-    const fix = isPortConflict
-      ? `Port ${port} is in use. Use '--mqtt-port ${port + 1}' or set protocols.mqtt.port in template.`
-      : "Check the MQTT configuration in your template file.";
-    throw new MiravoError(`MQTT adapter failed to start: ${message}`, fix);
-  }
+  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 } : {}),
+  };
 }
 
-// ---------------------------------------------------------------------------
-// Step 5a: OPC UA adapter
-// ---------------------------------------------------------------------------
-
-async function startOPCUAAdapter(
-  engine: Engine,
+function buildOPCUADefaultConfig(
   template: MiravoTemplate,
   portOverride: number | undefined,
   hostOverride: string | undefined,
   simulationName: string,
-): Promise<{ adapter: OPCUAAdapter; endpoint: string } | null> {
+  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 } : {}),
+  };
+}
 
-  opcuaLog.debug(`starting adapter · endpoint: opc.tcp://${host}:${port}`);
-
-  const opcuaAdapter = new OPCUAAdapter(engine.bus, engine);
-  try {
-    const resolvedConfig = {
-      name: "opcua" as const,
-      enabled: true,
-      port,
-      host,
-      security: opcuaConfig?.security ?? "none",
-      simulationName,
-      ...(opcuaConfig?.buildInfo ? { buildInfo: opcuaConfig.buildInfo } : {}),
-    };
-
-    await opcuaAdapter.start(resolvedConfig);
-    engine.registerAdapter(opcuaAdapter);
+/** 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);
+}
 
-    const endpoint = `opc.tcp://${host === "0.0.0.0" ? "localhost" : host}:${port}`;
-    opcuaLog.ready(`server ready · endpoint: ${colors.cyan(endpoint)}`);
-    return { adapter: opcuaAdapter, endpoint };
-  } catch (error) {
-    const message = error instanceof Error ? error.message : String(error);
-    const isPortConflict = message.includes("EADDRINUSE") || message.includes("in use");
-    const fix = isPortConflict
-      ? `Port ${port} is in use. Use '--opcua-port ${port + 1}'.`
-      : "Check the OPC UA port/network settings and retry.";
-    throw new MiravoError(`OPC UA adapter failed to start: ${message}`, fix);
-  }
+/** 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}`;
 }
 
 // ---------------------------------------------------------------------------
@@ -1022,6 +1756,17 @@ function subscribeToEvents(engine: Engine, errorContextCounts: Map<string, numbe
     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(
@@ -1040,6 +1785,7 @@ function subscribeToEvents(engine: Engine, errorContextCounts: Map<string, numbe
   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);
@@ -1047,6 +1793,7 @@ function subscribeToEvents(engine: Engine, errorContextCounts: Map<string, numbe
     engine.bus.off("fault:cleared", onFaultCleared);
     engine.bus.off("engine:warn", onWarn);
     engine.bus.off("engine:error", onError);
+    engine.bus.off("engine:reset", onReset);
   };
 }
 
@@ -1072,6 +1819,113 @@ export function incrementErrorContextCount(counts: Map<string, number>, rawConte
   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",
+    );
+
+  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,
+    },
+  ];
+}
+
+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;
+  }
+
+  opcuaLog.ready(
+    `server ready · endpoint: ${colors.cyan(String((result.data as Record<string, unknown>)?.["endpoint"] ?? ""))}`,
+  );
+}
+
 function startPeriodicSummary(
   engine: Engine,
   intervalSeconds: number,
@@ -1135,17 +1989,13 @@ function printDryRunSummary(
   // Instance summary
   let totalInstances = 0;
   let totalMembers = 0;
-  for (const area of template.areas) {
-    for (const line of area.lines) {
-      for (const twin of line.twins) {
-        totalInstances += twin.count;
-        const model = models.get(twin.model);
-        if (model) {
-          totalMembers += twin.count * Object.keys(model.members).length;
-        }
-      }
+  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(