mstro-app 0.5.0 → 0.5.5

package/server/services/websocket/session-registry.ts

@@ -1,5 +1,4 @@
 // Copyright (c) 2025-present Mstro, Inc. All rights reserved.
-// Licensed under the MIT License. See LICENSE file for details.
 
 /**
  * Session Registry — Persistent tab-to-session mapping
@@ -13,6 +12,19 @@
 
 import { existsSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs'
 import { join } from 'node:path'
+import type { EngineId } from './types.js'
+
+/**
+ * Per-tab engine override persisted alongside the tab record. Survives
+ * WebSocket disconnects + process restarts — the web client re-reads it on
+ * `tabInitialized` / `activeTabs` to restore the picker state after a
+ * reconnect.
+ */
+export interface TabEngineOverride {
+  engine: EngineId
+  model: string
+  effortLevel: string
+}
 
 export interface RegisteredTab {
   sessionId: string
@@ -30,6 +42,12 @@ export interface RegisteredTab {
   hasPersistedHistory?: boolean
   worktreePath?: string
   worktreeBranch?: string
+  /**
+   * Per-tab engine override. Absent when the tab uses the global defaults —
+   * authored from the web via `setTabEngine`, cleared by passing `null` to
+   * {@link SessionRegistry.updateTabEngineOverride}.
+   */
+  engineOverride?: TabEngineOverride
 }
 
 interface RegistryData {
@@ -242,6 +260,24 @@ export class SessionRegistry {
     }
   }
 
+  /**
+   * Update or clear the per-tab engine override. Pass `null` to remove the
+   * override and route future prompts through the global defaults. Writes
+   * through to disk so the override survives WS disconnects — that's the
+   * core persistence guarantee of IS-019.
+   */
+  updateTabEngineOverride(tabId: string, override: TabEngineOverride | null): void {
+    const tab = this.data.tabs[tabId]
+    if (!tab) return
+    if (override === null) {
+      delete tab.engineOverride
+    } else {
+      tab.engineOverride = { ...override }
+    }
+    tab.lastActivityAt = new Date().toISOString()
+    this.save()
+  }
+
   /**
    * Reorder tabs. Accepts an ordered array of tabIds and reassigns order values.
    */

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

@@ -1,25 +1,61 @@
 // Copyright (c) 2025-present Mstro, Inc. All rights reserved.
-// Licensed under the MIT License. See LICENSE file for details.
 
 import { spawn } from 'node:child_process';
 import { existsSync, mkdirSync, unlinkSync, writeFileSync } from 'node:fs';
 import { join } from 'node:path';
-import { getSettings, setEffortLevel, setModel } from '../settings.js';
+import {
+  getSettings,
+  isEngineSwapEnabled,
+  setBouncerClassifier,
+  setEffortLevel,
+  setModel,
+} from '../settings.js';
 import type { HandlerContext } from './handler-context.js';
 import type { WebSocketMessage, WSContext } from './types.js';
 
+/**
+ * Return the stored settings with the resolved `engineSwap` boolean patched
+ * in, so web clients always see the effective flag value (env-var override,
+ * NODE_ENV default, etc.) rather than the raw — possibly `undefined` —
+ * stored field.
+ */
+function getSettingsWithResolvedFlags() {
+  return { ...getSettings(), engineSwap: isEngineSwapEnabled() };
+}
+
 export function handleGetSettings(ctx: HandlerContext, ws: WSContext): void {
-  ctx.send(ws, { type: 'settings', data: getSettings() });
+  ctx.send(ws, { type: 'settings', data: getSettingsWithResolvedFlags() });
 }
 
-export function handleUpdateSettings(ctx: HandlerContext, _ws: WSContext, msg: WebSocketMessage): void {
+export function handleUpdateSettings(ctx: HandlerContext, ws: WSContext, msg: WebSocketMessage): void {
   if (msg.data?.model !== undefined) {
     setModel(msg.data.model);
   }
   if (msg.data?.effortLevel !== undefined) {
     setEffortLevel(msg.data.effortLevel);
   }
-  ctx.broadcastToAll({ type: 'settingsUpdated', data: getSettings() });
+  if (msg.data?.bouncerClassifier !== undefined) {
+    try {
+      setBouncerClassifier(msg.data.bouncerClassifier);
+    } catch (err) {
+      // Reject crafted payloads (non-eligible model, bad engine) — surface
+      // the reason to the requester and skip the broadcast so other clients
+      // keep showing the previous valid config.
+      const message = err instanceof Error ? err.message : String(err);
+      ctx.send(ws, {
+        type: 'error',
+        data: {
+          scope: 'bouncerClassifier',
+          message,
+        },
+      });
+      // Still echo the current settings back to the requester so the UI can
+      // revert its optimistic update.
+      ctx.send(ws, { type: 'settings', data: getSettingsWithResolvedFlags() });
+      return;
+    }
+  }
+  ctx.broadcastToAll({ type: 'settingsUpdated', data: getSettingsWithResolvedFlags() });
 }
 
 export async function generateNotificationSummary(

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

@@ -1,5 +1,4 @@
 // Copyright (c) 2025-present Mstro, Inc. All rights reserved.
-// Licensed under the MIT License. See LICENSE file for details.
 
 import { execSync } from 'node:child_process';
 import { existsSync, readdirSync, readFileSync } from 'node:fs';

package/server/services/websocket/skill-watcher.ts

@@ -1,5 +1,4 @@
 // Copyright (c) 2025-present Mstro, Inc. All rights reserved.
-// Licensed under the MIT License. See LICENSE file for details.
 
 import { type FSWatcher, watch } from 'node:fs';
 import { findSkillsDir } from '../../utils/paths.js';

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

@@ -1,5 +1,4 @@
 // Copyright (c) 2025-present Mstro, Inc. All rights reserved.
-// Licensed under the MIT License. See LICENSE file for details.
 
 /**
  * Tab-scoped broadcast helper.
@@ -17,22 +16,30 @@
  */
 
 import type { HandlerContext } from './handler-context.js'
-import type { WebSocketResponse } from './types.js'
+import type { EngineId, WebSocketResponse } from './types.js'
 
 type TabScopedEventType = WebSocketResponse['type']
 
 /**
  * Record + broadcast a tab-scoped event in one call. Returns the assigned
  * sequence number purely for logging/tests — callers rarely need it.
+ *
+ * `engine` is optional: when supplied (typically by session-driven movement
+ * events), it rides on the wire envelope so the web client can render
+ * engine-specific affordances. Buffer replay preserves it because the engine
+ * is part of the envelope produced for each broadcast.
  */
 export function broadcastTabEvent(
   ctx: HandlerContext,
   tabId: string,
   type: TabScopedEventType,
   data: unknown,
+  engine?: EngineId,
 ): number {
   const buffer = ctx.tabEventBuffers.getOrCreate(tabId)
   const seq = buffer.record(type, data)
-  ctx.broadcastToAll({ type, tabId, data, seq })
+  const envelope: WebSocketResponse = { type, tabId, data, seq }
+  if (engine) envelope.engine = engine
+  ctx.broadcastToAll(envelope)
   return seq
 }

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

@@ -1,5 +1,4 @@
 // Copyright (c) 2025-present Mstro, Inc. All rights reserved.
-// Licensed under the MIT License. See LICENSE file for details.
 
 /**
  * Tab event buffer — monotonic, bounded replay log for tab-scoped broadcasts.
@@ -43,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,
   ) {}
 
   /**
@@ -70,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
   }
@@ -79,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()
@@ -89,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
@@ -99,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
+  }
 }
 
 /**
@@ -153,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

@@ -1,5 +1,4 @@
 // Copyright (c) 2025-present Mstro, Inc. All rights reserved.
-// Licensed under the MIT License. See LICENSE file for details.
 
 /**
  * Replay tab-scoped events missed during a transport gap.
@@ -14,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) {
@@ -39,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

@@ -1,14 +1,14 @@
 // Copyright (c) 2025-present Mstro, Inc. All rights reserved.
-// Licensed under the MIT License. See LICENSE file for details.
 
 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,
@@ -18,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> {
@@ -37,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 } : {}),
   };
 }
 
@@ -102,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);
 
@@ -110,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;
@@ -134,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(),
     }
   });
@@ -149,6 +195,7 @@ export async function handleCreateTab(ctx: HandlerContext, ws: WSContext, workin
   ctx.send(ws, {
     type: 'tabInitialized',
     tabId,
+    engine,
     data: session.getSessionInfo()
   });
 }