mstro-app 0.5.1 → 0.5.6

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

@@ -7,7 +7,42 @@ import { runQualityScan } from './quality-service.js';
 import type { SessionRegistry } from './session-registry.js';
 import { resolveSkillPrompt } from './skill-handlers.js';
 import { broadcastTabEvent } from './tab-broadcast.js';
-import type { WebSocketMessage, WSContext } from './types.js';
+import { type EngineId, normalizeEngineId, type WebSocketMessage, type WSContext } from './types.js';
+
+/**
+ * Apply per-prompt engine/model/effortLevel overrides from the `execute`
+ * WebSocket payload onto the session. `session.options` is mutated in place
+ * so the next `executePrompt` call (which reads options.model / effortLevel
+ * inside the retry loop) picks up the new values without needing a new
+ * session. Pass-through for undefined fields — global defaults already live
+ * on the session from initialization.
+ */
+function applyExecuteOverrides(
+  session: ImprovisationSessionManager,
+  data: { engine?: unknown; model?: unknown; effortLevel?: unknown },
+): void {
+  const options = (session as unknown as { options: { model?: string; effortLevel?: string } }).options;
+  if (typeof data.model === 'string' && data.model.length > 0) {
+    options.model = data.model;
+  }
+  if (typeof data.effortLevel === 'string' && data.effortLevel.length > 0) {
+    options.effortLevel = data.effortLevel;
+  }
+  if (data.engine === 'claude-code' || data.engine === 'opencode') {
+    // Record the engine on the session history so `resolveEngineForSession`
+    // returns the user-chosen value on subsequent movementStart /
+    // movementComplete broadcasts. The actual engine factory swap happens
+    // at session-start (later-epic work); per-prompt engine flips flow
+    // through here so model/effort stay in sync.
+    const history = (session as unknown as { history: { engine: string } }).history;
+    history.engine = data.engine;
+  }
+}
+
+/** Resolve the engine for a session, defaulting to 'claude-code' for pre-engine sessions. */
+export function resolveEngineForSession(session: ImprovisationSessionManager | undefined): EngineId {
+  return normalizeEngineId(session?.engine);
+}
 
 // Re-export from extracted modules for backward compatibility
 export { handleHistoryMessage } from './session-history.js';
@@ -213,6 +248,10 @@ export function buildOutputHistory(session: ImprovisationSessionManager): Array<
  */
 export function setupSessionListeners(ctx: HandlerContext, session: ImprovisationSessionManager, _ws: WSContext, tabId: string): void {
   session.removeAllListeners();
+  // Bind tabId before listeners — the headless runner reads it at executePrompt
+  // time to wire AskUserQuestion routing back to this tab's web clients.
+  session.setTabId(tabId);
+  const engine = resolveEngineForSession(session);
 
   session.on('onHistoryPersisted', () => {
     const registry = ctx.getRegistry('');
@@ -227,19 +266,19 @@ export function setupSessionListeners(ctx: HandlerContext, session: Improvisatio
     broadcastTabEvent(ctx, tabId, 'thinking', { text });
   });
 
-  session.on('onMovementStart', (sequenceNumber: number, prompt: string, isAutoContinue?: boolean) => {
-    broadcastTabEvent(ctx, tabId, 'movementStart', { sequenceNumber, prompt, timestamp: Date.now(), executionStartTimestamp: session.executionStartTimestamp, isAutoContinue });
-    ctx.broadcastToAll({ type: 'tabStateChanged', data: { tabId, isExecuting: true, executionStartTimestamp: session.executionStartTimestamp } });
+  session.on('onMovementStart', (sequenceNumber: number, prompt: string, isAutoContinue?: boolean, etaProfile?: import('../../cli/eta-estimator.js').EtaProfile | null) => {
+    broadcastTabEvent(ctx, tabId, 'movementStart', { sequenceNumber, prompt, timestamp: Date.now(), executionStartTimestamp: session.executionStartTimestamp, isAutoContinue, etaProfile: etaProfile ?? undefined }, engine);
+    ctx.broadcastToAll({ type: 'tabStateChanged', engine, data: { tabId, isExecuting: true, executionStartTimestamp: session.executionStartTimestamp } });
   });
 
   session.on('onMovementComplete', (movement: Record<string, unknown>) => {
-    broadcastTabEvent(ctx, tabId, 'movementComplete', movement);
+    broadcastTabEvent(ctx, tabId, 'movementComplete', movement, engine);
 
     const registry = ctx.getRegistry('');
     // Use a try/catch since getRegistry may not have been initialized with the right workingDir
     try { registry.markTabUnviewed(tabId); } catch { /* ignore */ }
 
-    ctx.broadcastToAll({ type: 'tabStateChanged', data: { tabId, isExecuting: false, hasUnviewedCompletion: true } });
+    ctx.broadcastToAll({ type: 'tabStateChanged', engine, data: { tabId, isExecuting: false, hasUnviewedCompletion: true } });
 
     if (ctx.usageReporter && movement.tokensUsed) {
       ctx.usageReporter({
@@ -257,12 +296,12 @@ export function setupSessionListeners(ctx: HandlerContext, session: Improvisatio
   });
 
   session.on('onMovementError', (error: Error) => {
-    broadcastTabEvent(ctx, tabId, 'movementError', { message: error.message });
-    ctx.broadcastToAll({ type: 'tabStateChanged', data: { tabId, isExecuting: false } });
+    broadcastTabEvent(ctx, tabId, 'movementError', { message: error.message }, engine);
+    ctx.broadcastToAll({ type: 'tabStateChanged', engine, data: { tabId, isExecuting: false } });
   });
 
   session.on('onSessionUpdate', (history: Record<string, unknown>) => {
-    broadcastTabEvent(ctx, tabId, 'sessionUpdate', history);
+    broadcastTabEvent(ctx, tabId, 'sessionUpdate', history, engine);
   });
 
   session.on('onPlanNeedsConfirmation', (plan: Record<string, unknown>) => {
@@ -336,6 +375,13 @@ function handleExecuteMessage(ctx: HandlerContext, ws: WSContext, msg: WebSocket
     console.log(`[session] execute accepted msgId=${msgId} tabId=${tabId} sessionId=${sessionId}`);
   }
 
+  // Apply per-prompt engine/model/effort overrides from the payload. The
+  // web client populates these from the tab's effective EnginePicker state
+  // (override > global). Missing fields fall through to whatever the session
+  // already has — typically the machine-level defaults from `settings.json`
+  // applied at session init.
+  applyExecuteOverrides(session, msg.data);
+
   const worktreeDir = ctx.gitDirectories.get(tabId);
   const attachments = mergePreUploadedAttachments(ctx, tabId, msg.data.attachments);
 
@@ -346,6 +392,17 @@ function handleExecuteMessage(ctx: HandlerContext, ws: WSContext, msg: WebSocket
   const effectiveDir = worktreeDir || session.getSessionInfo().workingDir;
   const resolved = resolveSkillPrompt(rawPrompt, effectiveDir);
 
+  // Authoritative prompt-input clear for all connected devices. The submitter
+  // already cleared locally; this guarantees other devices clear even if the
+  // submitter's debounced syncPromptText never fires (e.g. mobile tab
+  // suspended after Send). Clients suppress this via locallyEditingTabs if
+  // the user is actively typing a new prompt.
+  ctx.broadcastToAll({
+    type: 'promptTextSync',
+    tabId,
+    data: { tabId, text: '' },
+  });
+
   session.executePrompt(
     resolved ? resolved.prompt : rawPrompt,
     attachments,
@@ -372,7 +429,7 @@ function handleNewSessionMessage(ctx: HandlerContext, ws: WSContext, tabId: stri
   if (tabMap) tabMap.set(tabId, newSessionId);
   const registry = ctx.getRegistry('');
   try { registry.updateTabSession(tabId, newSessionId); } catch { /* ignore */ }
-  ctx.send(ws, { type: 'newSession', tabId, data: newSession.getSessionInfo() });
+  ctx.send(ws, { type: 'newSession', tabId, engine: resolveEngineForSession(newSession), data: newSession.getSessionInfo() });
 }
 
 export function handleSessionMessage(ctx: HandlerContext, ws: WSContext, msg: WebSocketMessage, tabId: string, permission?: 'view'): void {

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

@@ -91,6 +91,7 @@ function getSessionById(workingDir: string, sessionId: string): Record<string, u
           startedAt: historyData.startedAt,
           lastActivityAt: historyData.lastActivityAt,
           totalTokens: historyData.totalTokens,
+          engine: historyData.engine || 'claude-code',
           movementCount: historyData.movements?.length || 0,
           title: firstPrompt.slice(0, 80) + (firstPrompt.length > 80 ? '...' : ''),
           movements: historyData.movements || [],
@@ -171,11 +172,13 @@ function buildSessionSummary(historyData: Record<string, unknown>): Record<strin
   const movementPreviews = (movements || []).slice(0, 3).map((m: Record<string, unknown>) => ({
     userPrompt: (typeof m.userPrompt === 'string' ? m.userPrompt : '').slice(0, 100) || ''
   }));
+  const engine = typeof historyData.engine === 'string' && historyData.engine ? historyData.engine : 'claude-code';
   return {
     sessionId: historyData.sessionId,
     startedAt: historyData.startedAt,
     lastActivityAt: historyData.lastActivityAt,
     totalTokens: historyData.totalTokens,
+    engine,
     movementCount: movements?.length || 0,
     title: firstPrompt.slice(0, 80) + (firstPrompt.length > 80 ? '...' : ''),
     movements: movementPreviews

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

@@ -1,11 +1,12 @@
 // Copyright (c) 2025-present Mstro, Inc. All rights reserved.
 
+import type { EtaProfile } from '../../cli/eta-estimator.js';
 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 { SessionRegistry } from './session-registry.js';
-import { replayTabEventsSince } from './tab-event-replay.js';
+import { buildOutputHistory, resolveEngineForSession, setupSessionListeners } from './session-handlers.js';
+import type { SessionRegistry, TabEngineOverride } from './session-registry.js';
+import { type ReplayResult, replayTabEventsSince } from './tab-event-replay.js';
 import type { WSContext } from './types.js';
 
 /**
@@ -22,6 +23,138 @@ function extractLastSeenSeq(data: unknown): number | undefined {
   return typeof candidate === 'number' && Number.isFinite(candidate) ? candidate : undefined;
 }
 
+/**
+ * When the session is mid-execution, expose the cached eta profile so the
+ * web's ComposingIndicator can render an ETA immediately on reconnect
+ * instead of waiting for the next movementStart (which won't fire until
+ * the user submits a fresh prompt).
+ */
+function inflightEtaPayload(session: ImprovisationSessionManager): { etaProfile?: EtaProfile } {
+  if (session.isExecuting && session.etaProfile) return { etaProfile: session.etaProfile };
+  return {};
+}
+
+/**
+ * Build the full-snapshot data payload for a `tabInitialized` message.
+ *
+ * Used in three situations:
+ *   1. Cold init (no `lastSeenSeq`) — web has no prior state to merge with.
+ *   2. Cold reattach (existing session, no prior seq) — same shape.
+ *   3. Replay-gap recovery — `replayTabEventsSince` returned `hadGap`, so
+ *      the web's incremental state is provably stale; we replace it.
+ *
+ * `replayGap` flags the recovery case so the web can branch: drop any
+ * already-rendered tab output and rebuild from `outputHistory` +
+ * `executionEvents` instead of merging on top of stale incremental state.
+ * Old web clients that don't know the flag still get the full snapshot and
+ * render correctly — `replayGap` is purely additive telemetry.
+ */
+function buildFullSnapshotData(
+  session: ImprovisationSessionManager,
+  options: {
+    worktreePath?: string;
+    worktreeBranch?: string;
+    engineOverride?: TabEngineOverride;
+    replayGap?: boolean;
+    extra?: Record<string, unknown>;
+  } = {},
+): Record<string, unknown> {
+  const isExecuting = session.isExecuting;
+  return {
+    ...session.getSessionInfo(),
+    engine: resolveEngineForSession(session),
+    outputHistory: buildOutputHistory(session),
+    isExecuting,
+    ...(isExecuting ? { executionEvents: session.getExecutionEventLog() } : {}),
+    ...(isExecuting && session.executionStartTimestamp
+      ? { executionStartTimestamp: session.executionStartTimestamp }
+      : {}),
+    ...inflightEtaPayload(session),
+    ...(options.worktreePath
+      ? { worktreePath: options.worktreePath, worktreeBranch: options.worktreeBranch }
+      : {}),
+    ...(options.engineOverride ? { engineOverride: options.engineOverride } : {}),
+    ...(options.replayGap ? { replayGap: true } : {}),
+    ...(options.extra ?? {}),
+  };
+}
+
+/**
+ * Snapshot vs incremental decision based on the replay outcome.
+ *
+ * - `incremental`: the web should keep its current state and append the
+ *   replayed events that already arrived (handled by `replayTabEventsSince`
+ *   itself when there's no gap). We send `tabInitialized` with
+ *   `resumedFromSeq: true`.
+ * - `snapshot`: the web should discard tab output and rebuild from a full
+ *   snapshot. Triggered either by `lastSeenSeq === undefined` (cold start)
+ *   or by `result.hadGap` (replay would silently skip events).
+ */
+function decideRecoveryMode(
+  result: ReplayResult,
+  lastSeenSeq: number | undefined,
+): 'incremental' | 'snapshot' {
+  if (lastSeenSeq === undefined) return 'snapshot';
+  if (result.hadGap) return 'snapshot';
+  return 'incremental';
+}
+
+/**
+ * Send `tabInitialized` for a resume path (`tryResumeFromDisk` /
+ * `resumeHistoricalSession`). Picks the snapshot or incremental envelope
+ * shape based on `mode` and threads any extra fields the caller needs to
+ * carry (e.g. `resumeFailed`, worktree state, engine override).
+ *
+ * Extracted to keep the resume call sites flat — without this helper, each
+ * caller pushes the function over the project's cognitive-complexity gate.
+ */
+function sendResumedTabInitialized(
+  ctx: HandlerContext,
+  ws: WSContext,
+  tabId: string,
+  session: ImprovisationSessionManager,
+  mode: 'incremental' | 'snapshot',
+  replay: ReplayResult,
+  options: {
+    worktreePath?: string;
+    worktreeBranch?: string;
+    engineOverride?: TabEngineOverride;
+    extra?: Record<string, unknown>;
+  } = {},
+): void {
+  const engine = resolveEngineForSession(session);
+  if (mode === 'snapshot') {
+    ctx.send(ws, {
+      type: 'tabInitialized',
+      tabId,
+      engine,
+      data: buildFullSnapshotData(session, {
+        worktreePath: options.worktreePath,
+        worktreeBranch: options.worktreeBranch,
+        engineOverride: options.engineOverride,
+        replayGap: replay.hadGap,
+        extra: options.extra,
+      }),
+    });
+    return;
+  }
+  ctx.send(ws, {
+    type: 'tabInitialized',
+    tabId,
+    engine,
+    data: {
+      ...session.getSessionInfo(),
+      engine,
+      resumedFromSeq: true,
+      ...(options.worktreePath
+        ? { worktreePath: options.worktreePath, worktreeBranch: options.worktreeBranch }
+        : {}),
+      ...(options.engineOverride ? { engineOverride: options.engineOverride } : {}),
+      ...(options.extra ?? {}),
+    },
+  });
+}
+
 function tryResumeFromDisk(
   ctx: HandlerContext,
   ws: WSContext,
@@ -54,16 +187,17 @@ function tryResumeFromDisk(
     // BEFORE tabInitialized so they arrive in the right order. Web-side
     // handlers append; `tabInitialized` does NOT reset when `resumedFromSeq`
     // is set, preserving the replayed additions.
-    replayTabEventsSince(ctx, ws, tabId, lastSeenSeq);
-
-    ctx.send(ws, {
-      type: 'tabInitialized',
-      tabId,
-      data: {
-        ...diskSession.getSessionInfo(),
-        ...(lastSeenSeq === undefined ? { outputHistory: buildOutputHistory(diskSession) } : { resumedFromSeq: true }),
-        ...(worktreePath ? { worktreePath, worktreeBranch } : {}),
-      }
+    //
+    // If `replayTabEventsSince` reports `hadGap`, no events were emitted and
+    // we fall back to a full-snapshot `tabInitialized` so the web replaces
+    // its (now-known-stale) incremental state instead of merging on top.
+    const replay = replayTabEventsSince(ctx, ws, tabId, lastSeenSeq);
+    const mode = decideRecoveryMode(replay, lastSeenSeq);
+
+    sendResumedTabInitialized(ctx, ws, tabId, diskSession, mode, replay, {
+      worktreePath,
+      worktreeBranch,
+      engineOverride: regTab?.engineOverride,
     });
     return true;
   } catch {
@@ -121,21 +255,32 @@ export async function initializeTab(ctx: HandlerContext, ws: WSContext, tabId: s
 
   registry.registerTab(tabId, sessionId, tabName || existingTab?.tabName);
   const registeredTab = registry.getTab(tabId);
-  ctx.broadcastToAll({
+  const engine = resolveEngineForSession(session);
+  // Mirror terminal-handlers.ts: broadcastToOthers, not broadcastToAll. The
+  // requesting client already drove this initTab and will receive
+  // `tabInitialized` below — echoing `tabCreated` back risks racing the
+  // discovery handler during a flicker and producing a phantom tab.
+  ctx.broadcastToOthers(ws, {
     type: 'tabCreated',
-    data: { tabId, tabName: registeredTab?.tabName || 'Chat', createdAt: registeredTab?.createdAt, order: registeredTab?.order, sessionInfo: session.getSessionInfo() }
+    engine,
+    data: { tabId, tabName: registeredTab?.tabName || 'Chat', createdAt: registeredTab?.createdAt, order: registeredTab?.order, engine, sessionInfo: session.getSessionInfo() }
   });
 
   // Fresh session (no disk/memory predecessor) has nothing to replay,
   // but we still pass lastSeenSeq through so the web flag is consistent.
-  replayTabEventsSince(ctx, ws, tabId, lastSeenSeq);
+  // hadGap is impossible here (buffer is empty for a brand-new tab), but
+  // route through `decideRecoveryMode` for uniformity with the resume paths.
+  const replay = replayTabEventsSince(ctx, ws, tabId, lastSeenSeq);
+  const mode = decideRecoveryMode(replay, lastSeenSeq);
 
   ctx.send(ws, {
     type: 'tabInitialized',
     tabId,
+    engine,
     data: {
       ...session.getSessionInfo(),
-      ...(lastSeenSeq !== undefined ? { resumedFromSeq: true } : {}),
+      ...(mode === 'incremental' ? { resumedFromSeq: true } : {}),
+      ...(replay.hadGap ? { replayGap: true } : {}),
     }
   });
 }
@@ -192,17 +337,14 @@ export async function resumeHistoricalSession(
 
   registry.registerTab(tabId, sessionId);
 
-  replayTabEventsSince(ctx, ws, tabId, lastSeenSeq);
+  const replay = replayTabEventsSince(ctx, ws, tabId, lastSeenSeq);
+  const mode = decideRecoveryMode(replay, lastSeenSeq);
 
-  ctx.send(ws, {
-    type: 'tabInitialized',
-    tabId,
-    data: {
-      ...session.getSessionInfo(),
-      ...(lastSeenSeq === undefined ? { outputHistory: buildOutputHistory(session) } : { resumedFromSeq: true }),
+  sendResumedTabInitialized(ctx, ws, tabId, session, mode, replay, {
+    extra: {
       resumeFailed: isNewSession,
-      originalSessionId: isNewSession ? historicalSessionId : undefined
-    }
+      originalSessionId: isNewSession ? historicalSessionId : undefined,
+    },
   });
 }
 
@@ -231,11 +373,14 @@ function reattachSession(
   const worktreePath = ctx.gitDirectories.get(tabId);
   const worktreeBranch = ctx.gitBranches.get(tabId);
 
-  // Fast path: the web already has local state (via Zustand), so just replay
-  // anything newer than `lastSeenSeq` and tell the client to skip the
-  // destructive reset in its tabInitialized handler.
-  if (lastSeenSeq !== undefined) {
-    replayTabEventsSince(ctx, ws, tabId, lastSeenSeq);
+  const inflightEta = inflightEtaPayload(session);
+  const replay = replayTabEventsSince(ctx, ws, tabId, lastSeenSeq);
+  const mode = decideRecoveryMode(replay, lastSeenSeq);
+
+  // Fast path: the web already has local state (via Zustand) AND the replay
+  // covered the gap cleanly — just replay the buffered events and tell the
+  // client to skip the destructive reset in its tabInitialized handler.
+  if (mode === 'incremental') {
     ctx.send(ws, {
       type: 'tabInitialized',
       tabId,
@@ -244,29 +389,27 @@ function reattachSession(
         resumedFromSeq: true,
         isExecuting: session.isExecuting,
         ...(session.isExecuting && session.executionStartTimestamp ? { executionStartTimestamp: session.executionStartTimestamp } : {}),
+        ...inflightEta,
         ...(worktreePath ? { worktreePath, worktreeBranch } : {}),
       }
     });
     return;
   }
 
-  // Cold-start reattach (no prior seq): send the full snapshot so the web
-  // can rebuild from scratch.
-  const outputHistory = buildOutputHistory(session);
-  const executionEvents = session.isExecuting
-    ? session.getExecutionEventLog()
-    : undefined;
-
+  // Snapshot path: either cold-start reattach (no prior seq) or replay-gap
+  // recovery (`hadGap=true`, no events sent). Both want a full snapshot so
+  // the web rebuilds from `outputHistory` + `executionEvents`. The
+  // `replayGap` flag distinguishes the two for telemetry — the wire
+  // payload shape is otherwise identical.
   ctx.send(ws, {
     type: 'tabInitialized',
     tabId,
-    data: {
-      ...session.getSessionInfo(),
-      outputHistory,
-      isExecuting: session.isExecuting,
-      executionEvents,
-      ...(session.isExecuting && session.executionStartTimestamp ? { executionStartTimestamp: session.executionStartTimestamp } : {}),
-      ...(worktreePath ? { worktreePath, worktreeBranch } : {}),
-    }
+    engine: resolveEngineForSession(session),
+    data: buildFullSnapshotData(session, {
+      worktreePath,
+      worktreeBranch,
+      engineOverride: regTab?.engineOverride,
+      replayGap: replay.hadGap,
+    }),
   });
 }

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

@@ -12,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
@@ -29,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 {
@@ -241,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

@@ -3,22 +3,59 @@
 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/tab-broadcast.ts

@@ -16,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
 }