mstro-app 0.1.54 → 0.1.57

package/server/services/websocket/handler.ts

@@ -13,6 +13,7 @@ import { existsSync, mkdirSync, readdirSync, readFileSync, unlinkSync, writeFile
 import { homedir } from 'node:os';
 import { dirname, join } from 'node:path';
 import { ImprovisationSessionManager } from '../../cli/improvisation-session-manager.js';
+import { AnalyticsEvents, trackEvent } from '../analytics.js';
 import {
   createDirectory,
   createFile,
@@ -22,9 +23,11 @@ import {
   writeFile
 } from '../files.js';
 import { captureException } from '../sentry.js';
+import { getModel, getSettings, setModel } from '../settings.js';
 import { getPTYManager } from '../terminal/pty-manager.js';
 import { AutocompleteService } from './autocomplete.js';
 import { readFileContent } from './file-utils.js';
+import { SessionRegistry } from './session-registry.js';
 import type { FrecencyData, GitDirectorySetResponse, GitFileStatus, GitLogEntry, GitRepoInfo, GitReposDiscoveredResponse, GitStatusResponse, WebSocketMessage, WebSocketResponse, WSContext } from './types.js';
 
 export interface UsageReport {
@@ -35,6 +38,38 @@ export interface UsageReport {
 
 export type UsageReporter = (report: UsageReport) => void;
 
+/** Convert a single movement record into OutputLine-compatible entries */
+function convertMovementToLines(movement: { userPrompt: string; timestamp: string; thinkingOutput?: string; toolUseHistory?: any[]; assistantResponse?: string; errorOutput?: string; tokensUsed: number }): any[] {
+  const lines: any[] = [];
+  const ts = new Date(movement.timestamp).getTime();
+
+  lines.push({ type: 'user', text: `> ${movement.userPrompt}`, timestamp: ts });
+
+  if (movement.thinkingOutput) {
+    lines.push({ type: 'thinking', text: '', thinking: movement.thinkingOutput, timestamp: ts });
+  }
+
+  if (movement.toolUseHistory) {
+    for (const tool of movement.toolUseHistory) {
+      lines.push({ type: 'tool-call', text: '', toolName: tool.toolName, toolInput: tool.toolInput || {}, timestamp: ts });
+      if (tool.result !== undefined) {
+        lines.push({ type: 'tool-result', text: '', toolResult: tool.result || 'No output', toolStatus: tool.isError ? 'error' : 'success', timestamp: ts });
+      }
+    }
+  }
+
+  if (movement.assistantResponse) {
+    lines.push({ type: 'assistant', text: movement.assistantResponse, timestamp: ts });
+  }
+
+  if (movement.errorOutput) {
+    lines.push({ type: 'error', text: `Error: ${movement.errorOutput}`, timestamp: ts });
+  }
+
+  lines.push({ type: 'system', text: `Command completed (tokens: ${movement.tokensUsed.toLocaleString()})`, timestamp: ts });
+  return lines;
+}
+
 export class WebSocketImproviseHandler {
   private sessions: Map<string, ImprovisationSessionManager> = new Map();
   private connections: Map<WSContext, Map<string, string>> = new Map();
@@ -43,6 +78,10 @@ export class WebSocketImproviseHandler {
   private usageReporter: UsageReporter | null = null;
   /** Per-tab selected git directory (tabId -> directory path) */
   private gitDirectories: Map<string, string> = new Map();
+  /** Persistent tab→session mapping that survives WS disconnections */
+  private sessionRegistry: SessionRegistry | null = null;
+  /** All connected WS contexts (for broadcasting to all clients) */
+  private allConnections: Set<WSContext> = new Set();
 
   constructor() {
     this.frecencyPath = join(homedir(), '.mstro', 'autocomplete-frecency.json');
@@ -50,6 +89,16 @@ export class WebSocketImproviseHandler {
     this.autocompleteService = new AutocompleteService(frecencyData);
   }
 
+  /**
+   * Lazily initialize session registry for a working directory
+   */
+  private getRegistry(workingDir: string): SessionRegistry {
+    if (!this.sessionRegistry) {
+      this.sessionRegistry = new SessionRegistry(workingDir);
+    }
+    return this.sessionRegistry;
+  }
+
   /**
    * Set the usage reporter callback for sending usage data to platform
    */
@@ -100,6 +149,7 @@ export class WebSocketImproviseHandler {
    */
   handleConnection(ws: WSContext, _workingDir: string): void {
     this.connections.set(ws, new Map());
+    this.allConnections.add(ws);
   }
 
   /**
@@ -134,7 +184,7 @@ export class WebSocketImproviseHandler {
         this.send(ws, { type: 'pong', tabId });
         return;
       case 'initTab':
-        return void await this.initializeTab(ws, tabId, workingDir);
+        return void await this.initializeTab(ws, tabId, workingDir, msg.data?.tabName);
       case 'resumeSession':
         if (!msg.data?.historicalSessionId) throw new Error('Historical session ID is required');
         return void await this.resumeHistoricalSession(ws, tabId, workingDir, msg.data.historicalSessionId);
@@ -172,6 +222,7 @@ export class WebSocketImproviseHandler {
       case 'createDirectory':
       case 'deleteFile':
       case 'renameFile':
+      case 'notifyFileOpened':
         return this.handleFileExplorerMessage(ws, msg, tabId, workingDir);
       case 'gitStatus':
       case 'gitStage':
@@ -183,6 +234,26 @@ export class WebSocketImproviseHandler {
       case 'gitDiscoverRepos':
       case 'gitSetDirectory':
         return this.handleGitMessage(ws, msg, tabId, workingDir);
+      // Session sync messages
+      case 'getActiveTabs':
+        return this.handleGetActiveTabs(ws, workingDir);
+      case 'createTab':
+        return void await this.handleCreateTab(ws, workingDir, msg.data?.tabName, msg.data?.optimisticTabId);
+      case 'reorderTabs':
+        return this.handleReorderTabs(ws, workingDir, msg.data?.tabOrder);
+      case 'syncTabMeta':
+        return this.handleSyncTabMeta(ws, msg, tabId, workingDir);
+      case 'syncPromptText':
+        return this.handleSyncPromptText(ws, msg, tabId);
+      case 'removeTab':
+        return this.handleRemoveTab(ws, tabId, workingDir);
+      case 'markTabViewed':
+        return this.handleMarkTabViewed(ws, tabId, workingDir);
+      // Settings messages
+      case 'getSettings':
+        return this.handleGetSettings(ws);
+      case 'updateSettings':
+        return this.handleUpdateSettings(ws, msg);
       default:
         throw new Error(`Unknown message type: ${msg.type}`);
     }
@@ -212,12 +283,16 @@ export class WebSocketImproviseHandler {
       }
       case 'new': {
         const oldSession = this.requireSession(ws, tabId);
-        const newSession = oldSession.startNewSession();
+        const newSession = oldSession.startNewSession({ model: getModel() });
         this.setupSessionListeners(newSession, ws, tabId);
         const newSessionId = newSession.getSessionInfo().sessionId;
         this.sessions.set(newSessionId, newSession);
         const tabMap = this.connections.get(ws);
         if (tabMap) tabMap.set(tabId, newSessionId);
+        // Update registry with new session ID
+        if (this.sessionRegistry) {
+          this.sessionRegistry.updateTabSession(tabId, newSessionId);
+        }
         this.send(ws, { type: 'newSession', tabId, data: newSession.getSessionInfo() });
         break;
       }
@@ -344,28 +419,81 @@ export class WebSocketImproviseHandler {
   private handleWriteFile(ws: WSContext, msg: WebSocketMessage, tabId: string, workingDir: string): void {
     if (!msg.data?.filePath) throw new Error('File path is required');
     if (msg.data.content === undefined) throw new Error('Content is required');
-    this.sendFileResult(ws, 'fileWritten', tabId, writeFile(msg.data.filePath, msg.data.content, workingDir));
+    const result = writeFile(msg.data.filePath, msg.data.content, workingDir);
+    this.sendFileResult(ws, 'fileWritten', tabId, result);
+    if (result.success) {
+      this.broadcastToOthers(ws, {
+        type: 'fileContentChanged',
+        data: { path: result.path, content: msg.data.content }
+      });
+    }
   }
 
   private handleCreateFile(ws: WSContext, msg: WebSocketMessage, tabId: string, workingDir: string): void {
     if (!msg.data?.filePath) throw new Error('File path is required');
-    this.sendFileResult(ws, 'fileCreated', tabId, createFile(msg.data.filePath, workingDir));
+    const result = createFile(msg.data.filePath, workingDir);
+    this.sendFileResult(ws, 'fileCreated', tabId, result);
+    if (result.success && result.path) {
+      const name = result.path.split('/').pop() || 'unknown';
+      this.broadcastToOthers(ws, {
+        type: 'fileCreated',
+        data: { path: result.path, name, size: 0, modifiedAt: new Date().toISOString() }
+      });
+    }
   }
 
   private handleCreateDirectory(ws: WSContext, msg: WebSocketMessage, tabId: string, workingDir: string): void {
     if (!msg.data?.dirPath) throw new Error('Directory path is required');
-    this.sendFileResult(ws, 'directoryCreated', tabId, createDirectory(msg.data.dirPath, workingDir));
+    const result = createDirectory(msg.data.dirPath, workingDir);
+    this.sendFileResult(ws, 'directoryCreated', tabId, result);
+    if (result.success && result.path) {
+      const name = result.path.split('/').pop() || 'unknown';
+      this.broadcastToOthers(ws, {
+        type: 'directoryCreated',
+        data: { path: result.path, name }
+      });
+    }
   }
 
   private handleDeleteFile(ws: WSContext, msg: WebSocketMessage, tabId: string, workingDir: string): void {
     if (!msg.data?.filePath) throw new Error('File path is required');
-    this.sendFileResult(ws, 'fileDeleted', tabId, deleteFile(msg.data.filePath, workingDir));
+    const result = deleteFile(msg.data.filePath, workingDir);
+    this.sendFileResult(ws, 'fileDeleted', tabId, result);
+    if (result.success && result.path) {
+      this.broadcastToOthers(ws, {
+        type: 'fileDeleted',
+        data: { path: result.path }
+      });
+    }
   }
 
   private handleRenameFile(ws: WSContext, msg: WebSocketMessage, tabId: string, workingDir: string): void {
     if (!msg.data?.oldPath) throw new Error('Old path is required');
     if (!msg.data?.newPath) throw new Error('New path is required');
-    this.sendFileResult(ws, 'fileRenamed', tabId, renameFile(msg.data.oldPath, msg.data.newPath, workingDir));
+    const result = renameFile(msg.data.oldPath, msg.data.newPath, workingDir);
+    this.sendFileResult(ws, 'fileRenamed', tabId, result);
+    if (result.success && result.path) {
+      const name = result.path.split('/').pop() || 'unknown';
+      this.broadcastToOthers(ws, {
+        type: 'fileRenamed',
+        data: { oldPath: msg.data.oldPath, newPath: result.path, name }
+      });
+    }
+  }
+
+  private handleNotifyFileOpened(ws: WSContext, msg: WebSocketMessage, workingDir: string): void {
+    if (!msg.data?.filePath) return;
+    const fileData = readFileContent(msg.data.filePath, workingDir);
+    if (!fileData.error) {
+      this.broadcastToOthers(ws, {
+        type: 'fileOpened',
+        data: {
+          path: msg.data.filePath,
+          fileName: fileData.fileName,
+          content: fileData.content
+        }
+      });
+    }
   }
 
   private handleFileExplorerMessage(ws: WSContext, msg: WebSocketMessage, tabId: string, workingDir: string): void {
@@ -376,6 +504,7 @@ export class WebSocketImproviseHandler {
       createDirectory: () => this.handleCreateDirectory(ws, msg, tabId, workingDir),
       deleteFile: () => this.handleDeleteFile(ws, msg, tabId, workingDir),
       renameFile: () => this.handleRenameFile(ws, msg, tabId, workingDir),
+      notifyFileOpened: () => this.handleNotifyFileOpened(ws, msg, workingDir),
     };
     handlers[msg.type]?.();
   }
@@ -406,11 +535,20 @@ export class WebSocketImproviseHandler {
 
     session.on('onMovementStart', (sequenceNumber: number, prompt: string) => {
       this.send(ws, { type: 'movementStart', tabId, data: { sequenceNumber, prompt, timestamp: Date.now() } });
+      // Broadcast execution state to ALL clients so tab indicators update
+      // even if per-tab event subscriptions aren't ready yet (e.g., newly discovered tabs)
+      this.broadcastToAll({ type: 'tabStateChanged', data: { tabId, isExecuting: true } });
     });
 
     session.on('onMovementComplete', (movement: any) => {
       this.send(ws, { type: 'movementComplete', tabId, data: movement });
 
+      // Mark tab as having unviewed completion (persisted across CLI restarts)
+      this.sessionRegistry?.markTabUnviewed(tabId);
+
+      // Broadcast execution state + completion dot to ALL clients
+      this.broadcastToAll({ type: 'tabStateChanged', data: { tabId, isExecuting: false, hasUnviewedCompletion: true } });
+
       // Report usage to platform if reporter is configured
       if (this.usageReporter && movement.tokensUsed) {
         this.usageReporter({
@@ -423,6 +561,8 @@ export class WebSocketImproviseHandler {
 
     session.on('onMovementError', (error: Error) => {
       this.send(ws, { type: 'movementError', tabId, data: { message: error.message } });
+      // Broadcast execution stopped to ALL clients
+      this.broadcastToAll({ type: 'tabStateChanged', data: { tabId, isExecuting: false } });
     });
 
     session.on('onSessionUpdate', (history: any) => {
@@ -450,17 +590,24 @@ export class WebSocketImproviseHandler {
     historicalSessionId: string
   ): Promise<void> {
     const tabMap = this.connections.get(ws);
+    const registry = this.getRegistry(workingDir);
 
+    // Check per-connection map first (same WS reconnect)
     const existingSessionId = tabMap?.get(tabId);
     if (existingSessionId) {
       const existingSession = this.sessions.get(existingSessionId);
       if (existingSession) {
-        this.setupSessionListeners(existingSession, ws, tabId);
-        this.send(ws, {
-          type: 'tabInitialized',
-          tabId,
-          data: existingSession.getSessionInfo()
-        });
+        this.reattachSession(existingSession, ws, tabId, registry);
+        return;
+      }
+    }
+
+    // Check session registry (cross-connection reattach)
+    const registrySessionId = registry.getTabSession(tabId);
+    if (registrySessionId) {
+      const inMemorySession = this.sessions.get(registrySessionId);
+      if (inMemorySession) {
+        this.reattachSession(inMemorySession, ws, tabId, registry);
         return;
       }
     }
@@ -469,13 +616,10 @@ export class WebSocketImproviseHandler {
     let isNewSession = false;
 
     try {
-      session = ImprovisationSessionManager.resumeFromHistory(workingDir, historicalSessionId);
+      session = ImprovisationSessionManager.resumeFromHistory(workingDir, historicalSessionId, { model: getModel() });
     } catch (error: any) {
-      // Historical session not found on disk - this can happen if the server
-      // restarted before any prompts were executed (history is only saved after
-      // the first prompt). Fall back to creating a fresh session.
       console.warn(`[WebSocketImproviseHandler] Could not resume session ${historicalSessionId}: ${error.message}. Creating new session.`);
-      session = new ImprovisationSessionManager({ workingDir });
+      session = new ImprovisationSessionManager({ workingDir, model: getModel() });
       isNewSession = true;
     }
 
@@ -488,12 +632,14 @@ export class WebSocketImproviseHandler {
       tabMap.set(tabId, sessionId);
     }
 
+    registry.registerTab(tabId, sessionId);
+
     this.send(ws, {
       type: 'tabInitialized',
       tabId,
       data: {
         ...session.getSessionInfo(),
-        // Let the client know if we had to create a new session instead of resuming
+        outputHistory: this.buildOutputHistory(session),
         resumeFailed: isNewSession,
         originalSessionId: isNewSession ? historicalSessionId : undefined
       }
@@ -501,26 +647,58 @@ export class WebSocketImproviseHandler {
   }
 
   /**
-   * Initialize a new tab with its own session
+   * Initialize a tab with its own session.
+   * Checks (in order): per-connection map → session registry → disk history → new session.
    */
-  private async initializeTab(ws: WSContext, tabId: string, workingDir: string): Promise<void> {
+  private async initializeTab(ws: WSContext, tabId: string, workingDir: string, tabName?: string): Promise<void> {
     const tabMap = this.connections.get(ws);
+    const registry = this.getRegistry(workingDir);
 
+    // 1. Check per-connection map (same WS reconnect)
     const existingSessionId = tabMap?.get(tabId);
     if (existingSessionId) {
       const existingSession = this.sessions.get(existingSessionId);
       if (existingSession) {
-        this.setupSessionListeners(existingSession, ws, tabId);
+        this.reattachSession(existingSession, ws, tabId, registry);
+        return;
+      }
+    }
+
+    // 2. Check session registry (cross-connection reattach, e.g. browser refresh)
+    const registrySessionId = registry.getTabSession(tabId);
+    if (registrySessionId) {
+      // Try in-memory first
+      const inMemorySession = this.sessions.get(registrySessionId);
+      if (inMemorySession) {
+        this.reattachSession(inMemorySession, ws, tabId, registry);
+        return;
+      }
+
+      // Try resuming from disk
+      try {
+        const diskSession = ImprovisationSessionManager.resumeFromHistory(workingDir, registrySessionId);
+        this.setupSessionListeners(diskSession, ws, tabId);
+        const diskSessionId = diskSession.getSessionInfo().sessionId;
+        this.sessions.set(diskSessionId, diskSession);
+        if (tabMap) tabMap.set(tabId, diskSessionId);
+        registry.touchTab(tabId);
+
         this.send(ws, {
           type: 'tabInitialized',
           tabId,
-          data: existingSession.getSessionInfo()
+          data: {
+            ...diskSession.getSessionInfo(),
+            outputHistory: this.buildOutputHistory(diskSession),
+          }
         });
         return;
+      } catch {
+        // Disk session not found — fall through to create new
       }
     }
 
-    const session = new ImprovisationSessionManager({ workingDir });
+    // 3. Create new session
+    const session = new ImprovisationSessionManager({ workingDir, model: getModel() });
     this.setupSessionListeners(session, ws, tabId);
 
     const sessionId = session.getSessionInfo().sessionId;
@@ -530,6 +708,13 @@ export class WebSocketImproviseHandler {
       tabMap.set(tabId, sessionId);
     }
 
+    registry.registerTab(tabId, sessionId, tabName);
+    const registeredTab = registry.getTab(tabId);
+    this.broadcastToAll({
+      type: 'tabCreated',
+      data: { tabId, tabName: registeredTab?.tabName || 'Chat', createdAt: registeredTab?.createdAt, order: registeredTab?.order, sessionInfo: session.getSessionInfo() }
+    });
+
     this.send(ws, {
       type: 'tabInitialized',
       tabId,
@@ -537,6 +722,92 @@ export class WebSocketImproviseHandler {
     });
   }
 
+  /**
+   * Reattach to an existing in-memory session.
+   * Sends output history (completed movements + in-progress events) for state restoration.
+   */
+  private reattachSession(
+    session: ImprovisationSessionManager,
+    ws: WSContext,
+    tabId: string,
+    registry: SessionRegistry
+  ): void {
+    this.setupSessionListeners(session, ws, tabId);
+
+    const tabMap = this.connections.get(ws);
+    const sessionId = session.getSessionInfo().sessionId;
+    if (tabMap) tabMap.set(tabId, sessionId);
+    registry.touchTab(tabId);
+
+    // Build output history from completed movements
+    const outputHistory = this.buildOutputHistory(session);
+
+    // If currently executing, append in-progress events
+    const executionEvents = session.isExecuting
+      ? session.getExecutionEventLog()
+      : undefined;
+
+    this.send(ws, {
+      type: 'tabInitialized',
+      tabId,
+      data: {
+        ...session.getSessionInfo(),
+        outputHistory,
+        isExecuting: session.isExecuting,
+        executionEvents,
+      }
+    });
+  }
+
+  /**
+   * Build OutputLine-compatible history from a session's completed movements.
+   * Converts MovementRecords into the same format the web client uses for display.
+   */
+  private buildOutputHistory(session: ImprovisationSessionManager): any[] {
+    const history = session.getHistory();
+    return history.movements.flatMap(convertMovementToLines);
+  }
+
+  /**
+   * Send a message to all connected clients EXCEPT the sender.
+   * Used for multi-client sync (e.g., tab created by one client, others should know).
+   */
+  private broadcastToOthers(sender: WSContext, response: WebSocketResponse): void {
+    for (const ws of this.allConnections) {
+      if (ws !== sender) {
+        this.send(ws, response);
+      }
+    }
+  }
+
+  /**
+   * Send a message to ALL connected clients (including sender).
+   */
+  private broadcastToAll(response: WebSocketResponse): void {
+    for (const ws of this.allConnections) {
+      this.send(ws, response);
+    }
+  }
+
+  // ========== Settings Handlers ==========
+
+  /**
+   * Return current machine-wide settings to the requesting client.
+   */
+  private handleGetSettings(ws: WSContext): void {
+    this.send(ws, { type: 'settings', data: getSettings() });
+  }
+
+  /**
+   * Update settings and broadcast to all connected clients.
+   */
+  private handleUpdateSettings(_ws: WSContext, msg: WebSocketMessage): void {
+    if (msg.data?.model !== undefined) {
+      setModel(msg.data.model);
+    }
+    this.broadcastToAll({ type: 'settingsUpdated', data: getSettings() });
+  }
+
   /**
    * Get session for a specific tab
    */
@@ -552,9 +823,17 @@ export class WebSocketImproviseHandler {
 
   /**
    * Handle connection close
+   * Note: Sessions are NOT destroyed — they persist for reconnection.
+   * Only the per-connection tab mapping is removed.
    */
   handleClose(ws: WSContext): void {
     this.connections.delete(ws);
+    this.allConnections.delete(ws);
+
+    // Remove ws from all terminal subscriber sets
+    for (const subs of this.terminalSubscribers.values()) {
+      subs.delete(ws);
+    }
   }
 
   /**
@@ -829,6 +1108,200 @@ export class WebSocketImproviseHandler {
   cleanupStaleSessions(): void {
   }
 
+  // ============================================
+  // Session sync methods
+  // ============================================
+
+  /**
+   * Handle getActiveTabs — returns all registered tabs and their state.
+   * Used by new clients (multi-device, multi-browser) to discover existing tabs.
+   */
+  private handleGetActiveTabs(ws: WSContext, workingDir: string): void {
+    const registry = this.getRegistry(workingDir);
+    const allTabs = registry.getAllTabs();
+
+    const tabs: Record<string, any> = {};
+    for (const [tabId, regTab] of Object.entries(allTabs)) {
+      const session = this.sessions.get(regTab.sessionId);
+      if (session) {
+        tabs[tabId] = {
+          tabName: regTab.tabName,
+          createdAt: regTab.createdAt,
+          order: regTab.order,
+          hasUnviewedCompletion: regTab.hasUnviewedCompletion,
+          sessionInfo: session.getSessionInfo(),
+          isExecuting: session.isExecuting,
+          outputHistory: this.buildOutputHistory(session),
+          executionEvents: session.isExecuting ? session.getExecutionEventLog() : undefined,
+        };
+      } else {
+        // Session not in memory — try to provide basic info from registry
+        tabs[tabId] = {
+          tabName: regTab.tabName,
+          createdAt: regTab.createdAt,
+          order: regTab.order,
+          hasUnviewedCompletion: regTab.hasUnviewedCompletion,
+          sessionId: regTab.sessionId,
+          isExecuting: false,
+          outputHistory: [],
+        };
+      }
+    }
+
+    this.send(ws, { type: 'activeTabs', data: { tabs } });
+  }
+
+  /**
+   * Handle syncTabMeta — update tab metadata (name) from a client.
+   */
+  private handleSyncTabMeta(_ws: WSContext, msg: WebSocketMessage, tabId: string, workingDir: string): void {
+    const registry = this.getRegistry(workingDir);
+    if (msg.data?.tabName) {
+      registry.updateTabName(tabId, msg.data.tabName);
+      // Broadcast rename to all clients (relay handles fan-out)
+      this.broadcastToAll({
+        type: 'tabRenamed',
+        data: { tabId, tabName: msg.data.tabName }
+      });
+    }
+  }
+
+  /**
+   * Handle syncPromptText — relay prompt text changes to all clients.
+   * Ephemeral: not persisted, just broadcast for live collaboration.
+   */
+  private handleSyncPromptText(_ws: WSContext, msg: WebSocketMessage, tabId: string): void {
+    if (typeof msg.data?.text !== 'string') return;
+    this.broadcastToAll({
+      type: 'promptTextSync',
+      tabId,
+      data: { tabId, text: msg.data.text }
+    });
+  }
+
+  /**
+   * Handle removeTab — client is removing a tab.
+   */
+  private handleRemoveTab(_ws: WSContext, tabId: string, workingDir: string): void {
+    const registry = this.getRegistry(workingDir);
+    registry.unregisterTab(tabId);
+
+    // Broadcast to all clients (broadcastToAll ensures relay-connected clients receive it)
+    this.broadcastToAll({
+      type: 'tabRemoved',
+      data: { tabId }
+    });
+  }
+
+  /**
+   * Handle markTabViewed — a client has viewed a tab's completed output.
+   * Persists viewed state and broadcasts to all clients so the green dot
+   * disappears on every device.
+   */
+  private handleMarkTabViewed(_ws: WSContext, tabId: string, workingDir: string): void {
+    const registry = this.getRegistry(workingDir);
+    registry.markTabViewed(tabId);
+
+    this.broadcastToAll({
+      type: 'tabViewed',
+      data: { tabId }
+    });
+  }
+
+  /**
+   * Handle createTab — CLI registers the tab and broadcasts to all clients.
+   *
+   * When optimisticTabId is provided, CLI reuses that ID as the authoritative tab ID.
+   * The requesting client already created a local tab with this ID (optimistic UI),
+   * so there's no reconciliation needed — the tab ID is the same everywhere.
+   * The initTab flow (useTabInit) will handle session creation for the requesting client.
+   *
+   * Other clients that don't have this tab will add it via the tabCreated broadcast.
+   */
+  private async handleCreateTab(ws: WSContext, workingDir: string, tabName?: string, optimisticTabId?: string): Promise<void> {
+    const registry = this.getRegistry(workingDir);
+
+    // Use the client's optimistic ID when available — avoids reconciliation.
+    // Fall back to server-generated ID if no optimistic ID provided.
+    const tabId = optimisticTabId || `tab-${Date.now()}-${Math.random().toString(36).slice(2, 6)}`;
+
+    // Check if this tab was already registered by initTab (race: useTabInit fires first)
+    const existingSession = registry.getTabSession(tabId);
+    if (existingSession) {
+      // Tab already initialized — broadcast to all clients.
+      // Must use broadcastToAll because all web clients share a single
+      // platformRelayContext — broadcastToOthers would skip the relay entirely,
+      // preventing other browser instances from discovering the new tab.
+      const regTab = registry.getTab(tabId);
+      this.broadcastToAll({
+        type: 'tabCreated',
+        data: {
+          tabId,
+          tabName: regTab?.tabName || 'Chat',
+          createdAt: regTab?.createdAt,
+          order: regTab?.order,
+          sessionInfo: this.sessions.get(existingSession)?.getSessionInfo(),
+        }
+      });
+      return;
+    }
+
+    // Create new session and register
+    const session = new ImprovisationSessionManager({ workingDir, model: getModel() });
+    this.setupSessionListeners(session, ws, tabId);
+
+    const sessionId = session.getSessionInfo().sessionId;
+    this.sessions.set(sessionId, session);
+
+    const tabMap = this.connections.get(ws);
+    if (tabMap) tabMap.set(tabId, sessionId);
+
+    registry.registerTab(tabId, sessionId, tabName);
+    const registeredTab = registry.getTab(tabId);
+
+    // Broadcast to ALL clients — the requesting client already has the tab
+    // (optimistic UI) and will ignore the duplicate via !currentTabs.has(tabId).
+    // Must use broadcastToAll so other browser instances via the shared
+    // platformRelayContext receive the tabCreated event.
+    this.broadcastToAll({
+      type: 'tabCreated',
+      data: {
+        tabId,
+        tabName: registeredTab?.tabName || 'Chat',
+        createdAt: registeredTab?.createdAt,
+        order: registeredTab?.order,
+        sessionInfo: session.getSessionInfo(),
+      }
+    });
+
+    // Send tabInitialized to the requesting client so useTabInit resolves
+    this.send(ws, {
+      type: 'tabInitialized',
+      tabId,
+      data: session.getSessionInfo()
+    });
+  }
+
+  /**
+   * Handle reorderTabs — client is reordering tabs.
+   */
+  private handleReorderTabs(_ws: WSContext, workingDir: string, tabOrder?: string[]): void {
+    if (!Array.isArray(tabOrder)) return;
+    const registry = this.getRegistry(workingDir);
+    registry.reorderTabs(tabOrder);
+
+    // Build order mapping for broadcast
+    const allTabs = registry.getAllTabs();
+    const orderMap = tabOrder
+      .filter((id) => allTabs[id])
+      .map((id) => ({ tabId: id, order: allTabs[id].order }));
+
+    this.broadcastToAll({
+      type: 'tabsReordered',
+      data: { tabOrder: orderMap }
+    });
+  }
+
   /**
    * Generate a notification summary using Claude Haiku
    * Sends the result as a notificationSummary message
@@ -1675,58 +2148,11 @@ Respond with ONLY the commit message, nothing else.`;
       return;
     }
 
-    // Clean up any existing listeners for this terminal to prevent duplicates
-    const existingCleanup = this.terminalListenerCleanups.get(terminalId);
-    if (existingCleanup) {
-      existingCleanup();
-    }
+    // Add this WS as a subscriber for this terminal's output
+    this.addTerminalSubscriber(terminalId, ws);
 
-    // Set up event listeners for this terminal
-    const onOutput = (tid: string, data: string) => {
-      if (tid === terminalId) {
-        this.send(ws, {
-          type: 'terminalOutput',
-          terminalId,
-          data: { output: data }
-        });
-      }
-    };
-
-    const onExit = (tid: string, exitCode: number) => {
-      if (tid === terminalId) {
-        this.send(ws, {
-          type: 'terminalExit',
-          terminalId,
-          data: { exitCode }
-        });
-        // Clean up listeners
-        ptyManager.off('output', onOutput);
-        ptyManager.off('exit', onExit);
-        ptyManager.off('error', onError);
-        this.terminalListenerCleanups.delete(terminalId);
-      }
-    };
-
-    const onError = (tid: string, error: string) => {
-      if (tid === terminalId) {
-        this.send(ws, {
-          type: 'terminalError',
-          terminalId,
-          data: { error }
-        });
-      }
-    };
-
-    ptyManager.on('output', onOutput);
-    ptyManager.on('exit', onExit);
-    ptyManager.on('error', onError);
-
-    // Store cleanup function for this terminal
-    this.terminalListenerCleanups.set(terminalId, () => {
-      ptyManager.off('output', onOutput);
-      ptyManager.off('exit', onExit);
-      ptyManager.off('error', onError);
-    });
+    // Set up broadcast listeners (idempotent — only creates once per terminal)
+    this.setupTerminalBroadcastListeners(terminalId);
 
     try {
       // Create or reconnect to the PTY process
@@ -1738,25 +2164,34 @@ Respond with ONLY the commit message, nothing else.`;
         requestedShell
       );
 
-      // If reconnecting, send scrollback buffer first
+      // If reconnecting, send scrollback buffer to THIS client only
       if (isReconnect) {
         const scrollback = ptyManager.getScrollback(terminalId);
         if (scrollback.length > 0) {
-          // Send scrollback as a single replay message
           this.send(ws, {
             type: 'terminalScrollback',
             terminalId,
             data: { lines: scrollback }
           });
         }
+      } else {
+        // New terminal — broadcast to other clients so they can create matching tabs
+        this.broadcastToOthers(ws, {
+          type: 'terminalCreated',
+          data: { terminalId, shell, cwd, persistent: false }
+        });
       }
 
-      // Send ready message
+      // Send ready message to THIS client
       this.send(ws, {
         type: 'terminalReady',
         terminalId,
         data: { shell, cwd, isReconnect }
       });
+      trackEvent(AnalyticsEvents.TERMINAL_SESSION_CREATED, {
+        shell,
+        is_reconnect: isReconnect,
+      });
     } catch (error: any) {
       console.error(`[WebSocketImproviseHandler] Failed to create terminal:`, error);
       this.send(ws, {
@@ -1764,11 +2199,7 @@ Respond with ONLY the commit message, nothing else.`;
         terminalId,
         data: { error: error.message || 'Failed to create terminal' }
       });
-      // Clean up listeners
-      ptyManager.off('output', onOutput);
-      ptyManager.off('exit', onExit);
-      ptyManager.off('error', onError);
-      this.terminalListenerCleanups.delete(terminalId);
+      this.removeTerminalSubscriber(terminalId, ws);
     }
   }
 
@@ -1790,59 +2221,13 @@ Respond with ONLY the commit message, nothing else.`;
       return;
     }
 
-    // Clean up any existing listeners for this terminal to prevent duplicates
-    const existingCleanup = this.terminalListenerCleanups.get(terminalId);
-    if (existingCleanup) {
-      existingCleanup();
-    }
+    // Add this WS as a subscriber for this terminal's output
+    this.addTerminalSubscriber(terminalId, ws);
 
-    // Set up event listeners for this terminal
-    const onOutput = (tid: string, data: string) => {
-      if (tid === terminalId) {
-        this.send(ws, {
-          type: 'terminalOutput',
-          terminalId,
-          data: { output: data }
-        });
-      }
-    };
+    // Set up broadcast listeners (idempotent — only creates once per terminal)
+    this.setupTerminalBroadcastListeners(terminalId);
 
-    const onExit = (tid: string, exitCode: number) => {
-      if (tid === terminalId) {
-        this.send(ws, {
-          type: 'terminalExit',
-          terminalId,
-          data: { exitCode }
-        });
-        ptyManager.off('output', onOutput);
-        ptyManager.off('exit', onExit);
-        ptyManager.off('error', onError);
-        this.terminalListenerCleanups.delete(terminalId);
-      }
-    };
-
-    const onError = (tid: string, error: string) => {
-      if (tid === terminalId) {
-        this.send(ws, {
-          type: 'terminalError',
-          terminalId,
-          data: { error }
-        });
-      }
-    };
-
-    ptyManager.on('output', onOutput);
-    ptyManager.on('exit', onExit);
-    ptyManager.on('error', onError);
-
-    // Store cleanup function for this terminal
-    this.terminalListenerCleanups.set(terminalId, () => {
-      ptyManager.off('output', onOutput);
-      ptyManager.off('exit', onExit);
-      ptyManager.off('error', onError);
-    });
-
-    // Send scrollback buffer
+    // Send scrollback buffer to THIS client only
     const scrollback = ptyManager.getScrollback(terminalId);
     if (scrollback.length > 0) {
       this.send(ws, {
@@ -1945,7 +2330,8 @@ Respond with ONLY the commit message, nothing else.`;
   /**
    * Handle terminal close
    */
-  private handleTerminalClose(_ws: WSContext, terminalId: string): void {
+  private handleTerminalClose(ws: WSContext, terminalId: string): void {
+    trackEvent(AnalyticsEvents.TERMINAL_SESSION_CLOSED);
 
     // Check if this is a persistent terminal first
     const persistentHandler = this.persistentHandlers.get(terminalId);
@@ -1955,19 +2341,27 @@ Respond with ONLY the commit message, nothing else.`;
       // For persistent terminals, close actually kills the tmux session
       const ptyManager = getPTYManager();
       ptyManager.closePersistent(terminalId);
-      return;
-    }
+    } else {
+      // Clean up event listeners
+      const listenerCleanup = this.terminalListenerCleanups.get(terminalId);
+      if (listenerCleanup) {
+        listenerCleanup();
+        this.terminalListenerCleanups.delete(terminalId);
+      }
 
-    // Clean up event listeners
-    const listenerCleanup = this.terminalListenerCleanups.get(terminalId);
-    if (listenerCleanup) {
-      listenerCleanup();
-      this.terminalListenerCleanups.delete(terminalId);
+      // Close regular PTY
+      const ptyManager = getPTYManager();
+      ptyManager.close(terminalId);
     }
 
-    // Otherwise use regular PTY
-    const ptyManager = getPTYManager();
-    ptyManager.close(terminalId);
+    // Clean up subscribers
+    this.terminalSubscribers.delete(terminalId);
+
+    // Broadcast to other clients
+    this.broadcastToOthers(ws, {
+      type: 'terminalClosed',
+      data: { terminalId }
+    });
   }
 
   // Persistent terminal handlers for tmux-backed sessions
@@ -1976,9 +2370,131 @@ Respond with ONLY the commit message, nothing else.`;
   // Track PTY event listener cleanup functions per terminal to prevent duplicate listeners
   private terminalListenerCleanups: Map<string, () => void> = new Map();
 
+  // Track which WS connections are subscribed to each terminal's output
+  private terminalSubscribers: Map<string, Set<WSContext>> = new Map();
+
+  /**
+   * Add a WS connection as a subscriber for terminal output.
+   */
+  private addTerminalSubscriber(terminalId: string, ws: WSContext): void {
+    let subs = this.terminalSubscribers.get(terminalId);
+    if (!subs) {
+      subs = new Set();
+      this.terminalSubscribers.set(terminalId, subs);
+    }
+    subs.add(ws);
+  }
+
+  /**
+   * Remove a WS subscriber from a terminal and clean up if no subscribers remain.
+   */
+  private removeTerminalSubscriber(terminalId: string, ws: WSContext): void {
+    const subs = this.terminalSubscribers.get(terminalId);
+    if (!subs) return;
+    subs.delete(ws);
+    if (subs.size > 0) return;
+    this.terminalSubscribers.delete(terminalId);
+    const cleanup = this.terminalListenerCleanups.get(terminalId);
+    if (cleanup) {
+      cleanup();
+      this.terminalListenerCleanups.delete(terminalId);
+    }
+  }
+
+  /**
+   * Attach persistent (tmux) terminal handlers for output/exit broadcasting.
+   */
+  private attachPersistentHandlers(terminalId: string, ptyManager: ReturnType<typeof getPTYManager>): void {
+    const handlers = ptyManager.attachPersistent(
+      terminalId,
+      (output: string) => {
+        const subs = this.terminalSubscribers.get(terminalId);
+        if (subs) {
+          for (const sub of subs) {
+            this.send(sub, { type: 'terminalOutput', terminalId, data: { output } });
+          }
+        }
+      },
+      (exitCode: number) => {
+        const subs = this.terminalSubscribers.get(terminalId);
+        if (subs) {
+          for (const sub of subs) {
+            this.send(sub, { type: 'terminalExit', terminalId, data: { exitCode } });
+          }
+        }
+        this.persistentHandlers.delete(terminalId);
+        this.terminalSubscribers.delete(terminalId);
+      }
+    );
+    if (handlers) {
+      this.persistentHandlers.set(terminalId, handlers);
+    }
+  }
+
+  /**
+   * Set up PTY event listeners that broadcast to all subscribers.
+   * Only creates listeners once per terminal (idempotent).
+   */
+  private setupTerminalBroadcastListeners(terminalId: string): void {
+    // Already set up - don't duplicate
+    if (this.terminalListenerCleanups.has(terminalId)) return;
+
+    const ptyManager = getPTYManager();
+
+    const onOutput = (tid: string, data: string) => {
+      if (tid === terminalId) {
+        const subs = this.terminalSubscribers.get(terminalId);
+        if (subs) {
+          for (const ws of subs) {
+            this.send(ws, { type: 'terminalOutput', terminalId, data: { output: data } });
+          }
+        }
+      }
+    };
+
+    const onExit = (tid: string, exitCode: number) => {
+      if (tid === terminalId) {
+        const subs = this.terminalSubscribers.get(terminalId);
+        if (subs) {
+          for (const ws of subs) {
+            this.send(ws, { type: 'terminalExit', terminalId, data: { exitCode } });
+          }
+        }
+        // Clean up
+        ptyManager.off('output', onOutput);
+        ptyManager.off('exit', onExit);
+        ptyManager.off('error', onError);
+        this.terminalListenerCleanups.delete(terminalId);
+        this.terminalSubscribers.delete(terminalId);
+      }
+    };
+
+    const onError = (tid: string, error: string) => {
+      if (tid === terminalId) {
+        const subs = this.terminalSubscribers.get(terminalId);
+        if (subs) {
+          for (const ws of subs) {
+            this.send(ws, { type: 'terminalError', terminalId, data: { error } });
+          }
+        }
+      }
+    };
+
+    ptyManager.on('output', onOutput);
+    ptyManager.on('exit', onExit);
+    ptyManager.on('error', onError);
+
+    this.terminalListenerCleanups.set(terminalId, () => {
+      ptyManager.off('output', onOutput);
+      ptyManager.off('exit', onExit);
+      ptyManager.off('error', onError);
+    });
+  }
+
   /**
    * Initialize a persistent (tmux-backed) terminal session
-   * These sessions survive server restarts
+   * These sessions survive server restarts.
+   * Uses subscriber pattern for multi-client output broadcasting.
    */
   private handleTerminalInitPersistent(
     ws: WSContext,
@@ -2001,6 +2517,9 @@ Respond with ONLY the commit message, nothing else.`;
       return;
     }
 
+    // Add this WS as a subscriber for this terminal's output
+    this.addTerminalSubscriber(terminalId, ws);
+
     try {
       // Create or reconnect to the persistent session
       const { shell, cwd, isReconnect } = ptyManager.createPersistent(
@@ -2011,31 +2530,12 @@ Respond with ONLY the commit message, nothing else.`;
         requestedShell
       );
 
-      // Attach to the session for I/O
-      const handlers = ptyManager.attachPersistent(
-        terminalId,
-        (output: string) => {
-          this.send(ws, {
-            type: 'terminalOutput',
-            terminalId,
-            data: { output }
-          });
-        },
-        (exitCode: number) => {
-          this.send(ws, {
-            type: 'terminalExit',
-            terminalId,
-            data: { exitCode }
-          });
-          this.persistentHandlers.delete(terminalId);
-        }
-      );
-
-      if (handlers) {
-        this.persistentHandlers.set(terminalId, handlers);
+      // Only attach if we don't already have handlers (first subscriber)
+      if (!this.persistentHandlers.has(terminalId)) {
+        this.attachPersistentHandlers(terminalId, ptyManager);
       }
 
-      // If reconnecting, send scrollback buffer first
+      // If reconnecting, send scrollback buffer to THIS client only
       if (isReconnect) {
         const scrollback = ptyManager.getPersistentScrollback(terminalId);
         if (scrollback.length > 0) {
@@ -2045,9 +2545,15 @@ Respond with ONLY the commit message, nothing else.`;
             data: { lines: scrollback }
           });
         }
+      } else {
+        // New terminal — broadcast to other clients so they can create matching tabs
+        this.broadcastToOthers(ws, {
+          type: 'terminalCreated',
+          data: { terminalId, shell, cwd, persistent: true }
+        });
       }
 
-      // Send ready message
+      // Send ready message to THIS client
       this.send(ws, {
         type: 'terminalReady',
         terminalId,
@@ -2060,6 +2566,7 @@ Respond with ONLY the commit message, nothing else.`;
         terminalId,
         data: { error: error.message || 'Failed to create persistent terminal' }
       });
+      this.removeTerminalSubscriber(terminalId, ws);
     }
   }