mstro-app 0.5.0 → 0.5.5

package/server/services/websocket/quality-tools.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 { spawn } from 'node:child_process';
 import { readdirSync, readFileSync, statSync } from 'node:fs';
@@ -104,7 +103,10 @@ async function tryInstallCommands(tool: QualityTool, dirPath: string): Promise<s
   let lastStderr = '';
   for (const cmd of commands) {
     const parts = cmd.trim().split(' ');
-    const result = await runCommand(parts[0], parts.slice(1), dirPath);
+    // Force NODE_ENV=development for install: npm/yarn/pnpm silently skip
+    // devDependencies under NODE_ENV=production, making `-D` installs no-op
+    // (exit 0, nothing installed) so the post-install detection re-fails.
+    const result = await runCommand(parts[0], parts.slice(1), dirPath, { NODE_ENV: 'development' });
     if (result.exitCode === 0) return null;
     lastStderr = result.stderr;
   }
@@ -258,6 +260,57 @@ export function filesByExt(files: SourceFile[], exts: string[]): string[] {
   return out;
 }
 
+/** Folders that signal "this whole tree is test code" by convention. */
+const TEST_FOLDER_SEGMENTS = ['__tests__', '__mocks__', 'tests', 'test', 'e2e', 'spec'];
+
+/** Filename regexes that mark a single file as a test, regardless of folder. */
+const TEST_FILE_PATTERNS: RegExp[] = [
+  /\.(test|spec)\.(ts|tsx|js|jsx|mjs|cjs|mts|cts)$/, // JS/TS .test/.spec
+  /_test\.(go|py)$/,                                  // Go / Python *_test
+  /^test_.+\.py$/,                                    // Python test_*.py
+];
+
+function pathHasTestFolder(path: string): boolean {
+  for (const segment of TEST_FOLDER_SEGMENTS) {
+    if (path.includes(`/${segment}/`) || path.startsWith(`${segment}/`)) return true;
+  }
+  return false;
+}
+
+function fileNameLooksLikeTest(name: string): boolean {
+  for (const pattern of TEST_FILE_PATTERNS) {
+    if (pattern.test(name)) return true;
+  }
+  return false;
+}
+
+/**
+ * Identify a path as a test/spec file. Test files are exempt from
+ * structural-length checks (long-file, long-function) because:
+ *
+ *   - A 600-line test file with 50 small `it()` blocks is easy to read,
+ *     each block is independent, and "split it" yields zero maintenance
+ *     benefit while harming discoverability.
+ *   - A 200-line test function (long Arrange-Act-Assert with helpers
+ *     inlined) is normal for feature coverage and not a complexity smell.
+ *
+ * Linters and security/bug findings still apply to test files — only the
+ * structural-length heuristics defer. Pattern-matches the conventions used
+ * by Code Climate's default-exclude set:
+ *
+ *   - JS/TS:  *.test.ts, *.test.tsx, *.spec.js, *.spec.jsx, *.test.mts, ...
+ *   - Folder: __tests__/, /tests/, /test/, e2e/, spec/, __mocks__/
+ *   - Python: test_*.py, *_test.py
+ *   - Go:     *_test.go
+ *   - Rust:   files inside `tests/` are integration tests by convention
+ */
+export function isTestFile(relativePath: string): boolean {
+  const path = relativePath.replace(/\\/g, '/').toLowerCase();
+  if (pathHasTestFolder(path)) return true;
+  const name = path.split('/').pop() ?? path;
+  return fileNameLooksLikeTest(name);
+}
+
 /**
  * Split a file list into chunks so a single command invocation doesn't
  * blow past ARG_MAX. macOS ARG_MAX is ~256KB; 400 paths at ~200 chars each
@@ -276,13 +329,19 @@ export function chunkFileList(paths: string[], size = 400): string[][] {
 // Command Runner
 // ============================================================================
 
-export function runCommand(cmd: string, args: string[], cwd: string): Promise<{ stdout: string; stderr: string; exitCode: number }> {
+export function runCommand(
+  cmd: string,
+  args: string[],
+  cwd: string,
+  envOverrides?: Record<string, string>,
+): Promise<{ stdout: string; stderr: string; exitCode: number }> {
   return new Promise((resolve) => {
     const proc = spawn(cmd, args, {
       cwd,
       shell: true,
       stdio: ['ignore', 'pipe', 'pipe'],
       timeout: 120000,
+      env: envOverrides ? { ...process.env, ...envOverrides } : undefined,
     });
     let stdout = '';
     let stderr = '';

package/server/services/websocket/quality-types.ts

@@ -1,10 +1,47 @@
 // Copyright (c) 2025-present Mstro, Inc. All rights reserved.
-// Licensed under the MIT License. See LICENSE file for details.
 
 // ============================================================================
 // Types
 // ============================================================================
 
+/**
+ * Letter grades produced by the multi-dimensional quality rating.
+ *
+ * Score → grade mapping (per product spec — note: no `D`; F covers 56-69, F-
+ * covers 0-55. `D` is retained ONLY for backward compatibility with reports
+ * persisted by older versions of this module — new code never emits it):
+ *
+ *   A+  97-100   A   93-96    A-  90-92
+ *   B+  87-89    B   83-86    B-  80-82
+ *   C+  77-79    C   73-76    C-  70-72
+ *   F+  65-69    F   56-64    F-  0-55
+ *
+ * `N/A` means the dimension had no tooling available to evaluate it.
+ */
+export type Grade =
+  | 'A+' | 'A' | 'A-'
+  | 'B+' | 'B' | 'B-'
+  | 'C+' | 'C' | 'C-'
+  | 'D' // legacy — only appears on reports persisted before the +/- rollout
+  | 'F+' | 'F' | 'F-'
+  | 'N/A';
+export type DimensionName = 'security' | 'reliability' | 'maintainability';
+
+export interface DimensionScore {
+  name: DimensionName;
+  score: number;
+  grade: Grade;
+  rationale: string;
+  available: boolean;
+  findingCount: number;
+  worstSeverity: 'critical' | 'high' | 'medium' | 'low' | null;
+}
+
+export interface QualityGate {
+  passed: boolean;
+  failingConditions: string[];
+}
+
 export interface QualityTool {
   name: string;
   installed: boolean;
@@ -15,8 +52,6 @@ export interface QualityTool {
 export interface CategoryScore {
   name: string;
   score: number;
-  weight: number;
-  effectiveWeight: number;
   available: boolean;
   issueCount?: number;
   details?: Record<string, unknown>;
@@ -62,12 +97,34 @@ export interface QualityResults {
   timestamp: string;
   ecosystem: string[];
   scoreBreakdown?: ScoreBreakdown;
+  dimensions?: DimensionScore[];
+  qualityGate?: QualityGate;
+  gradeRationale?: string;
+  /** Wall-clock duration of the CLI scan that produced this report. Used to estimate ETA on subsequent scans of the same directory. */
+  scanDurationMs?: number;
+  /** Wall-clock duration of the AI code-review pass, when one ran. */
+  reviewDurationMs?: number;
 }
 
 export interface ScanProgress {
   step: string;
   current: number;
   total: number;
+  /**
+   * Wall-clock estimate of the total scan duration, in milliseconds. Sent on
+   * the first progress event of a scan and again on subsequent events so
+   * reconnecting clients still get an ETA. The web subtracts elapsed time to
+   * render "≈ X remaining".
+   */
+  etaMs?: number;
+  /**
+   * Server-side timestamp (ms since epoch) of when the scan started — paired
+   * with `etaMs` so the web can compute elapsed time without trusting its
+   * own clock alignment.
+   */
+  startedAt?: number;
+  /** Optional sub-step detail used by long-running steps (e.g. "tsc --noEmit, 18s elapsed") to keep the UI from looking stuck. */
+  detail?: string;
 }
 
 export type Ecosystem = 'node' | 'python' | 'rust' | 'go' | 'swift' | 'kotlin' | 'unknown';
@@ -143,7 +200,7 @@ export const ADDITIONAL_EXCLUDES = new Set([
 
 export const FILE_LENGTH_THRESHOLD = 300;
 export const FUNCTION_LENGTH_THRESHOLD = 50;
-export const TOTAL_STEPS = 7;
+export const TOTAL_STEPS = 8;
 
 export function hasInstalledToolInCategory(
   installedSet: Set<string>,

package/server/services/websocket/session-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 { type FileAttachment, ImprovisationSessionManager } from '../../cli/improvisation-session-manager.js';
 import { getEffortLevel, getModel } from '../settings.js';
@@ -8,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';
@@ -214,6 +248,7 @@ export function buildOutputHistory(session: ImprovisationSessionManager): Array<
  */
 export function setupSessionListeners(ctx: HandlerContext, session: ImprovisationSessionManager, _ws: WSContext, tabId: string): void {
   session.removeAllListeners();
+  const engine = resolveEngineForSession(session);
 
   session.on('onHistoryPersisted', () => {
     const registry = ctx.getRegistry('');
@@ -228,19 +263,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({
@@ -258,12 +293,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>) => {
@@ -337,6 +372,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);
 
@@ -347,6 +389,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,
@@ -373,7 +426,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

@@ -1,5 +1,4 @@
 // Copyright (c) 2025-present Mstro, Inc. All rights reserved.
-// Licensed under the MIT License. See LICENSE file for details.
 
 import { existsSync, readdirSync, readFileSync, unlinkSync } from 'node:fs';
 import { readFile } from 'node:fs/promises';
@@ -92,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 || [],
@@ -172,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,12 +1,12 @@
 // Copyright (c) 2025-present Mstro, Inc. All rights reserved.
-// Licensed under the MIT License. See LICENSE file for details.
 
+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';
 
 /**
@@ -23,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,
@@ -55,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 {
@@ -122,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 } : {}),
     }
   });
 }
@@ -193,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,
+    },
   });
 }
 
@@ -232,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,
@@ -245,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,
+    }),
   });
 }