mstro-app 0.5.1 → 0.5.5

package/server/services/websocket/tab-event-buffer.ts

@@ -42,22 +42,59 @@ export interface BufferedEvent {
   data: unknown
   /** `Date.now()` at record time. Used for age-based eviction. */
   timestamp: number
+  /**
+   * Approximate serialized byte size of `data`. Computed once at record
+   * time so eviction can enforce a memory cap without re-stringifying on
+   * every check. Type and seq overhead is small; we only bill `data` here.
+   */
+  byteSize: number
 }
 
 /**
  * Bounded replay log for a single tab.
  *
- * Size/age limits are parameterised for testability but defaulted to values
- * that comfortably cover real-world reconnect windows.
+ * Size/age/byte limits are parameterised for testability but defaulted to
+ * values that comfortably cover real-world reconnect windows for long-running
+ * coding-agent tasks (multi-tool, multi-minute).
+ *
+ * ## Replay-gap detection
+ *
+ * The buffer tracks `evictedThroughSeq` — the highest seq that has ever been
+ * evicted (0 if nothing has been evicted). A web client whose `lastSeenSeq`
+ * is below this value has missed events the buffer can no longer supply, and
+ * an incremental replay would produce a silent gap. Callers should consult
+ * `hasGapSince` before relying on `getSince` for incremental replay; on a
+ * gap they should fall back to a full snapshot path (e.g. `outputHistory`).
+ *
+ * ## Eviction is FIFO with three caps
+ *
+ * Events are evicted from the front when ANY of these limits is exceeded:
+ *  - count: `maxEvents` (default 10k)
+ *  - age:   `maxAgeMs` (default 60 min)
+ *  - bytes: `maxTotalBytes` (default 32 MB)
+ *
+ * The byte cap is the safety belt against pathological events (e.g. a 50 MB
+ * grep result streamed as one event). Without it, count- and age-based caps
+ * still allow a single tab to hoard arbitrary memory.
  */
 export class TabEventBuffer {
   private readonly events: BufferedEvent[] = []
   private nextSeq = 1
+  /**
+   * Highest seq that has been evicted from the buffer. 0 means nothing has
+   * been evicted yet (buffer is operating within its window). Monotonically
+   * non-decreasing — eviction always happens from the front of the FIFO, in
+   * seq order, so the most recently evicted seq is always the highest.
+   */
+  private evictedThroughSeq = 0
+  /** Approximate sum of `byteSize` over still-resident events. */
+  private totalBytes = 0
 
   constructor(
     private readonly maxEvents: number = DEFAULT_MAX_EVENTS,
     private readonly maxAgeMs: number = DEFAULT_MAX_AGE_MS,
     private readonly now: () => number = Date.now,
+    private readonly maxTotalBytes: number = DEFAULT_MAX_TOTAL_BYTES,
   ) {}
 
   /**
@@ -69,7 +106,9 @@ export class TabEventBuffer {
    */
   record(type: string, data: unknown): number {
     const seq = this.nextSeq++
-    this.events.push({ seq, type, data, timestamp: this.now() })
+    const byteSize = estimateByteSize(data)
+    this.events.push({ seq, type, data, timestamp: this.now(), byteSize })
+    this.totalBytes += byteSize
     this.evict()
     return seq
   }
@@ -78,6 +117,11 @@ export class TabEventBuffer {
    * Return all still-buffered events with `seq > afterSeq`, in original
    * order. Returns an empty array if nothing newer is buffered (either the
    * web is caught up or the window has rolled past).
+   *
+   * NOTE: This does not detect or signal replay gaps. Pair with
+   * `hasGapSince(afterSeq)` to know whether a returned array is a complete
+   * incremental replay or a partial one (events between `afterSeq` and the
+   * oldest surviving seq have been evicted and are no longer available).
    */
   getSince(afterSeq: number): BufferedEvent[] {
     this.evict()
@@ -88,6 +132,29 @@ export class TabEventBuffer {
     return out
   }
 
+  /**
+   * True when an incremental replay starting from `afterSeq` would silently
+   * skip events that the buffer has already evicted. Used by the replay
+   * orchestrator to decide whether to fall back to a full snapshot rather
+   * than emit a partial event stream the web can't reconstruct.
+   *
+   * `afterSeq < evictedThroughSeq` means the next event the caller expects
+   * (`afterSeq + 1`) is at or below the eviction frontier — that event has
+   * already been dropped from memory.
+   */
+  hasGapSince(afterSeq: number): boolean {
+    this.evict()
+    return afterSeq < this.evictedThroughSeq
+  }
+
+  /**
+   * Highest seq that has been evicted from this buffer; 0 if nothing has been
+   * evicted yet. Exposed for telemetry and gap-recovery decisions.
+   */
+  getEvictedThroughSeq(): number {
+    return this.evictedThroughSeq
+  }
+
   /** Current highest assigned seq (monotonic; not reset by eviction). */
   currentSeq(): number {
     return this.nextSeq - 1
@@ -98,20 +165,66 @@ export class TabEventBuffer {
     return this.events.length
   }
 
+  /** Approximate bytes held by `data` payloads currently in memory. For tests/telemetry. */
+  byteSize(): number {
+    return this.totalBytes
+  }
+
   /**
    * Drop events older than `maxAgeMs` from the front, then enforce
-   * `maxEvents` by trimming the front further if needed. Eviction keeps the
-   * newest events — they're the ones the web is most likely to still need.
+   * `maxEvents` and `maxTotalBytes` by trimming the front further if needed.
+   * Eviction keeps the newest events — they're the ones the web is most
+   * likely to still need.
+   *
+   * Each evicted seq advances `evictedThroughSeq` so callers can detect
+   * replay gaps. The FIFO ensures we always evict in seq order, so the last
+   * evicted seq is always the highest seen so far.
+   *
+   * The byte cap is enforced LAST so that count- and age-based eviction get
+   * a chance first; a chatty-but-small session evicts on age before it ever
+   * touches the byte cap, which keeps the usual case predictable.
    */
   private evict(): void {
     const cutoff = this.now() - this.maxAgeMs
     while (this.events.length > 0 && this.events[0].timestamp < cutoff) {
-      this.events.shift()
+      this.popOldest()
     }
     while (this.events.length > this.maxEvents) {
-      this.events.shift()
+      this.popOldest()
+    }
+    while (this.events.length > 0 && this.totalBytes > this.maxTotalBytes) {
+      this.popOldest()
     }
   }
+
+  private popOldest(): void {
+    const evicted = this.events.shift()
+    if (!evicted) return
+    this.evictedThroughSeq = evicted.seq
+    this.totalBytes -= evicted.byteSize
+    if (this.totalBytes < 0) this.totalBytes = 0
+  }
+}
+
+/**
+ * Estimate `data`'s serialized byte size for the eviction byte cap. Uses
+ * `JSON.stringify` because that's what hits the wire; falls back to a small
+ * default on circular structures so we don't crash the broadcast path.
+ *
+ * `Buffer.byteLength` would give us UTF-8 bytes vs UTF-16 code units, but on
+ * Node `JSON.stringify(...).length` is close enough (within a small constant
+ * factor for ASCII-heavy payloads) and avoids an extra allocation.
+ */
+function estimateByteSize(data: unknown): number {
+  if (data === undefined || data === null) return 0
+  try {
+    return JSON.stringify(data).length
+  } catch {
+    // Circular reference, BigInt, etc. — bill a small fixed cost so the
+    // byte cap still has SOME signal. We won't be able to wire-serialize
+    // this either, but that's a separate problem.
+    return 256
+  }
 }
 
 /**
@@ -152,7 +265,26 @@ export class TabEventBufferRegistry {
   }
 }
 
-/** 1000 events per tab covers typical reconnect windows comfortably. */
-export const DEFAULT_MAX_EVENTS = 1000
-/** 15 minutes of history is more than enough for the longest plausible web reconnect. */
-export const DEFAULT_MAX_AGE_MS = 15 * 60 * 1000
+/**
+ * 10,000 events per tab.
+ *
+ * Sized for long-running coding-agent tasks (multi-tool, multi-minute) plus
+ * laptop sleep/wake reconnect windows. Worst-case observed: a 14-minute
+ * session with ~120 tool calls produces ~1.5–3k tab-scoped events; 10× that
+ * gives headroom for parallel agents and chatty improvisation. Memory
+ * footprint at ~500B/event = ~5MB per tab; the local-only single-tenant
+ * deployment makes this a non-issue.
+ */
+export const DEFAULT_MAX_EVENTS = 10_000
+/**
+ * 60 minutes of history. Covers laptop sleep/wake, long meetings between
+ * sessions, and the largest plausible reconnect window that a tab might
+ * legitimately want to recover incrementally instead of starting fresh.
+ */
+export const DEFAULT_MAX_AGE_MS = 60 * 60 * 1000
+/**
+ * 32 MB safety belt against pathological events (large grep results, full
+ * file reads streamed inline). Eviction by bytes guarantees a single tab
+ * can't hoard arbitrary memory regardless of count/age limits.
+ */
+export const DEFAULT_MAX_TOTAL_BYTES = 32 * 1024 * 1024

package/server/services/websocket/tab-event-replay.ts

@@ -13,23 +13,88 @@
  * events live.
  */
 
+import { captureException } from '../sentry.js'
 import type { HandlerContext } from './handler-context.js'
 import type { WebSocketResponse, WSContext } from './types.js'
 
+/** Result of a replay attempt — used by callers (and tests) for telemetry. */
+export interface ReplayResult {
+  /** Number of events sent to the web during this replay. */
+  sentCount: number
+  /**
+   * True when the buffer had already evicted events that fell between the
+   * web's `lastSeenSeq` and the oldest surviving seq. The replay is partial;
+   * the web's incremental state is now provably stale and the caller should
+   * fall back to a full snapshot path (e.g. `outputHistory`).
+   */
+  hadGap: boolean
+  /**
+   * If `hadGap`, the highest seq that was evicted (so the gap range is
+   * `(lastSeenSeq + 1) .. evictedThroughSeq`). Undefined when no gap.
+   */
+  evictedThroughSeq?: number
+  /**
+   * If `hadGap`, the seq the web requested replay from. Echoed into
+   * telemetry so log entries are self-contained.
+   */
+  lastSeenSeq?: number
+}
+
 /**
  * Replay tab events with `seq > lastSeenSeq` to `ws`. Silently no-ops when
  * the buffer is empty or `lastSeenSeq` is unset (full init, not a resume).
+ *
+ * Returns a `ReplayResult` so the caller can detect a partial replay (the
+ * buffer evicted events the web is asking about) and decide whether to send
+ * a recovery snapshot. This is the load-bearing telemetry surface for the
+ * "long-running task output disappears mid-stream" failure mode — a `hadGap`
+ * here is the smoking gun.
  */
 export function replayTabEventsSince(
   ctx: HandlerContext,
   ws: WSContext,
   tabId: string,
   lastSeenSeq: number | undefined,
-): void {
-  if (lastSeenSeq === undefined) return
+): ReplayResult {
+  if (lastSeenSeq === undefined) return { sentCount: 0, hadGap: false }
 
   const buffer = ctx.tabEventBuffers.get(tabId)
-  if (!buffer) return
+  if (!buffer) return { sentCount: 0, hadGap: false }
+
+  const hadGap = buffer.hasGapSince(lastSeenSeq)
+  const evictedThroughSeq = hadGap ? buffer.getEvictedThroughSeq() : undefined
+
+  if (hadGap) {
+    // Replay is structurally incomplete. Surface a single, structured warning
+    // so we can grep/Sentry-search for the failure mode without spamming logs
+    // on every event.
+    const message =
+      `[tab-replay] gap detected for tab=${tabId}: web requested replay from seq=${lastSeenSeq}, ` +
+      `but buffer has evicted through seq=${evictedThroughSeq}. ` +
+      `Events (${lastSeenSeq + 1}..${evictedThroughSeq}) are unavailable; the web's ` +
+      `incremental state is stale and a full snapshot will be sent instead.`
+    console.warn(message)
+    try {
+      captureException(new Error('TabEventBuffer replay gap'), {
+        context: 'tab-event-replay',
+        tabId,
+        lastSeenSeq,
+        evictedThroughSeq,
+        bufferCurrentSeq: buffer.currentSeq(),
+        gapSize: (evictedThroughSeq ?? 0) - lastSeenSeq,
+      })
+    } catch {
+      // Sentry transport errors must not break the replay path.
+    }
+    // CRITICAL: do NOT emit partial events. If we did, the web would advance
+    // its `tabSeqs` past the (lastSeenSeq+1 .. evictedThroughSeq) range and
+    // the subsequent snapshot would land in a tab that thinks it's caught up
+    // — silently rendering only the post-gap tail. Returning early without
+    // events forces the caller (`session-initialization.ts`) into the
+    // snapshot-fallback branch, which sends a fresh `outputHistory` payload
+    // with `replayGap: true` so the web can replace its tab state cleanly.
+    return { sentCount: 0, hadGap: true, evictedThroughSeq, lastSeenSeq }
+  }
 
   const events = buffer.getSince(lastSeenSeq)
   for (const event of events) {
@@ -38,4 +103,6 @@ export function replayTabEventsSince(
     // `WebSocketResponse['type']`. Narrow here without an extra runtime check.
     ctx.send(ws, { type: event.type as WebSocketResponse['type'], tabId, data: event.data, seq: event.seq })
   }
+
+  return { sentCount: events.length, hadGap: false, lastSeenSeq }
 }

package/server/services/websocket/tab-handlers.ts

@@ -3,11 +3,12 @@
 import { ImprovisationSessionManager } from '../../cli/improvisation-session-manager.js';
 import { getEffortLevel, getModel } from '../settings.js';
 import type { HandlerContext } from './handler-context.js';
-import { buildOutputHistory, setupSessionListeners } from './session-handlers.js';
-import type { WebSocketMessage, WSContext } from './types.js';
+import { buildOutputHistory, resolveEngineForSession, setupSessionListeners } from './session-handlers.js';
+import type { TabEngineOverride } from './session-registry.js';
+import { DEFAULT_ENGINE_ID, type EngineId, type WebSocketMessage, type WSContext } from './types.js';
 
 function buildActiveTabData(
-  regTab: { tabName: string; createdAt: string; order: number; hasUnviewedCompletion?: boolean; sessionId: string },
+  regTab: { tabName: string; createdAt: string; order: number; hasUnviewedCompletion?: boolean; sessionId: string; engineOverride?: TabEngineOverride },
   session: ImprovisationSessionManager,
   worktreePath: string | undefined,
   worktreeBranch: string | undefined,
@@ -17,17 +18,19 @@ function buildActiveTabData(
     createdAt: regTab.createdAt,
     order: regTab.order,
     hasUnviewedCompletion: regTab.hasUnviewedCompletion,
+    engine: resolveEngineForSession(session),
     sessionInfo: session.getSessionInfo(),
     isExecuting: session.isExecuting,
     outputHistory: buildOutputHistory(session),
     executionEvents: session.isExecuting ? session.getExecutionEventLog() : undefined,
     ...(session.isExecuting && session.executionStartTimestamp ? { executionStartTimestamp: session.executionStartTimestamp } : {}),
     ...(worktreePath ? { worktreePath, worktreeBranch } : {}),
+    ...(regTab.engineOverride ? { engineOverride: regTab.engineOverride } : {}),
   };
 }
 
 function buildInactiveTabData(
-  regTab: { tabName: string; createdAt: string; order: number; hasUnviewedCompletion?: boolean; sessionId: string },
+  regTab: { tabName: string; createdAt: string; order: number; hasUnviewedCompletion?: boolean; sessionId: string; engineOverride?: TabEngineOverride },
   worktreePath: string | undefined,
   worktreeBranch: string | undefined,
 ): Record<string, unknown> {
@@ -36,10 +39,12 @@ function buildInactiveTabData(
     createdAt: regTab.createdAt,
     order: regTab.order,
     hasUnviewedCompletion: regTab.hasUnviewedCompletion,
+    engine: DEFAULT_ENGINE_ID,
     sessionId: regTab.sessionId,
     isExecuting: false,
     outputHistory: [],
     ...(worktreePath ? { worktreePath, worktreeBranch } : {}),
+    ...(regTab.engineOverride ? { engineOverride: regTab.engineOverride } : {}),
   };
 }
 
@@ -101,6 +106,41 @@ export function handleMarkTabViewed(ctx: HandlerContext, _ws: WSContext, tabId:
   });
 }
 
+/**
+ * Persist a per-tab engine override. `msg.data.override` is either a full
+ * `{ engine, model, effortLevel }` payload or `null` to clear the override.
+ * Persisted via the session registry so the override survives WebSocket
+ * disconnects — the core guarantee of IS-019. Broadcasts the change to all
+ * connected clients so multi-device sessions stay in sync.
+ */
+export function handleSetTabEngine(ctx: HandlerContext, _ws: WSContext, msg: WebSocketMessage, tabId: string, workingDir: string): void {
+  const raw = msg.data?.override;
+  let override: TabEngineOverride | null;
+  if (raw === null || raw === undefined) {
+    override = null;
+  } else if (
+    typeof raw === 'object' &&
+    (raw.engine === 'claude-code' || raw.engine === 'opencode') &&
+    typeof raw.model === 'string' && raw.model.length > 0 &&
+    typeof raw.effortLevel === 'string' && raw.effortLevel.length > 0
+  ) {
+    override = { engine: raw.engine, model: raw.model, effortLevel: raw.effortLevel };
+  } else {
+    // Malformed payload — ignore rather than crash. The client will re-emit
+    // from the canonical server-side value on the next reconnect.
+    return;
+  }
+
+  const registry = ctx.getRegistry(workingDir);
+  registry.updateTabEngineOverride(tabId, override);
+
+  ctx.broadcastToAll({
+    type: 'tabEngineOverride',
+    tabId,
+    data: { tabId, override },
+  });
+}
+
 export async function handleCreateTab(ctx: HandlerContext, ws: WSContext, workingDir: string, tabName?: string, optimisticTabId?: string): Promise<void> {
   const registry = ctx.getRegistry(workingDir);
 
@@ -109,14 +149,18 @@ export async function handleCreateTab(ctx: HandlerContext, ws: WSContext, workin
   const existingSession = registry.getTabSession(tabId);
   if (existingSession) {
     const regTab = registry.getTab(tabId);
+    const existingSessionObj = ctx.sessions.get(existingSession);
+    const engine: EngineId = resolveEngineForSession(existingSessionObj);
     ctx.broadcastToAll({
       type: 'tabCreated',
+      engine,
       data: {
         tabId,
         tabName: regTab?.tabName || 'Chat',
         createdAt: regTab?.createdAt,
         order: regTab?.order,
-        sessionInfo: ctx.sessions.get(existingSession)?.getSessionInfo(),
+        engine,
+        sessionInfo: existingSessionObj?.getSessionInfo(),
       }
     });
     return;
@@ -133,14 +177,17 @@ export async function handleCreateTab(ctx: HandlerContext, ws: WSContext, workin
 
   registry.registerTab(tabId, sessionId, tabName);
   const registeredTab = registry.getTab(tabId);
+  const engine: EngineId = resolveEngineForSession(session);
 
   ctx.broadcastToAll({
     type: 'tabCreated',
+    engine,
     data: {
       tabId,
       tabName: registeredTab?.tabName || 'Chat',
       createdAt: registeredTab?.createdAt,
       order: registeredTab?.order,
+      engine,
       sessionInfo: session.getSessionInfo(),
     }
   });
@@ -148,6 +195,7 @@ export async function handleCreateTab(ctx: HandlerContext, ws: WSContext, workin
   ctx.send(ws, {
     type: 'tabInitialized',
     tabId,
+    engine,
     data: session.getSessionInfo()
   });
 }

package/server/services/websocket/types.ts

@@ -37,11 +37,11 @@ const GitWorktreeMessages = ['gitWorktreeList', 'gitWorktreeCreate', 'gitWorktre
 
 const GitMergeMessages = ['gitMergePreview', 'gitWorktreeMerge', 'gitMergeAbort', 'gitMergeComplete', 'gitMergeStashPop', 'gitMergeDiscardBlockers'] as const;
 
-const SessionSyncMessages = ['getActiveTabs', 'createTab', 'reorderTabs', 'syncTabMeta', 'removeTab', 'markTabViewed'] as const;
+const SessionSyncMessages = ['getActiveTabs', 'createTab', 'reorderTabs', 'syncTabMeta', 'removeTab', 'markTabViewed', 'setTabEngine'] as const;
 
 const SettingsMessages = ['getSettings', 'updateSettings'] as const;
 
-const QualityMessages = ['qualityDetectTools', 'qualityScan', 'qualityInstallTools', 'qualityCodeReview', 'qualityLoadState', 'qualitySaveDirectories'] as const;
+const QualityMessages = ['qualityDetectTools', 'qualityScan', 'qualityInstallTools', 'qualityCodeReview', 'qualityCancel', 'qualityLoadState', 'qualityClearPending', 'qualitySaveDirectories'] as const;
 
 const FileUploadMessages = ['fileUploadStart', 'fileUploadChunk', 'fileUploadComplete', 'fileUploadCancel'] as const;
 
@@ -55,6 +55,8 @@ const PlanSprintMessages = ['planCreateSprint', 'planActivateSprint', 'planCompl
 
 const SkillMessages = ['listSkills', 'chatToBoard'] as const;
 
+const InstanceMessages = ['shutdownInstance'] as const;
+
 type WebSocketMessageType =
   | typeof CoreMessages[number]
   | typeof TerminalMessages[number]
@@ -73,12 +75,33 @@ type WebSocketMessageType =
   | typeof PlanMessages[number]
   | typeof PlanBoardMessages[number]
   | typeof PlanSprintMessages[number]
-  | typeof SkillMessages[number];
+  | typeof SkillMessages[number]
+  | typeof InstanceMessages[number];
+
+/**
+ * AI engine identifier carried on WebSocket envelopes so the web client can
+ * render engine-specific affordances. Server relay forwards the field
+ * unchanged; missing values on inbound messages default to 'claude-code'.
+ */
+export type EngineId = 'claude-code' | 'opencode';
+
+export const DEFAULT_ENGINE_ID: EngineId = 'claude-code';
+
+/** Narrow an unknown engine value to a valid EngineId, defaulting to 'claude-code'. */
+export function normalizeEngineId(value: unknown): EngineId {
+  return value === 'opencode' ? 'opencode' : DEFAULT_ENGINE_ID;
+}
 
 export interface WebSocketMessage {
   type: WebSocketMessageType;
   tabId?: string;
   terminalId?: string;
+  /**
+   * Engine that produced / should handle this message. Optional on the wire —
+   * missing field is treated as 'claude-code' by receivers. Populated on
+   * prompt-send, session-state, and tab-state messages.
+   */
+  engine?: EngineId;
   // biome-ignore lint/suspicious/noExplicitAny: message envelope carries heterogeneous payloads — typed per-handler via destructuring
   data?: any;
   /** Injected by server relay for view-only shared users */
@@ -103,7 +126,7 @@ const GitWorktreeResponseMessages = ['gitWorktreeListResult', 'gitWorktreeCreate
 
 const GitMergeResponseMessages = ['gitMergePreviewResult', 'gitWorktreeMergeResult', 'gitMergeAborted', 'gitMergeCompleted', 'gitMergeStashPopped', 'gitMergeBlockersDiscarded'] as const;
 
-const SessionSyncResponseMessages = ['activeTabs', 'tabCreated', 'tabRemoved', 'tabRenamed', 'tabsReordered', 'tabViewed', 'tabStateChanged'] as const;
+const SessionSyncResponseMessages = ['activeTabs', 'tabCreated', 'tabRemoved', 'tabRenamed', 'tabsReordered', 'promptTextSync', 'tabViewed', 'tabStateChanged', 'tabEngineOverride'] as const;
 
 const SettingsResponseMessages = ['settings', 'settingsUpdated'] as const;
 
@@ -121,6 +144,8 @@ const PlanSprintResponseMessages = ['planSprintCreated', 'planSprintUpdated', 'p
 
 const SkillResponseMessages = ['skillsList', 'chatToBoardCreated'] as const;
 
+const InstanceResponseMessages = ['shuttingDown'] as const;
+
 type WebSocketResponseType =
   | typeof CoreResponseMessages[number]
   | typeof TerminalResponseMessages[number]
@@ -139,12 +164,19 @@ type WebSocketResponseType =
   | typeof PlanResponseMessages[number]
   | typeof PlanBoardResponseMessages[number]
   | typeof PlanSprintResponseMessages[number]
-  | typeof SkillResponseMessages[number];
+  | typeof SkillResponseMessages[number]
+  | typeof InstanceResponseMessages[number];
 
 export interface WebSocketResponse {
   type: WebSocketResponseType;
   tabId?: string;
   terminalId?: string;
+  /**
+   * Engine that produced this response. Populated by CLI handlers for
+   * prompt-send, session-state, and tab-state message categories so the web
+   * client can render engine-specific affordances.
+   */
+  engine?: EngineId;
   // biome-ignore lint/suspicious/noExplicitAny: message envelope carries heterogeneous payloads — typed per-handler via destructuring
   data?: any;
   /**