mstro-app 0.4.51 → 0.5.0

package/server/services/platform.ts

@@ -90,9 +90,17 @@ export class PlatformConnection {
     this.startedAt = new Date().toISOString()
   }
 
-  private async maybeRefreshToken(): Promise<void> {
+  /**
+   * Refresh the device token if it's older than the refresh interval.
+   * Returns `true` if the token is (still) valid after this call, `false`
+   * if refresh was attempted and rejected with an auth error — in which
+   * case the caller should surface an auth-expired signal to the web
+   * rather than silently reusing a dead token.
+   */
+  private async maybeRefreshToken(): Promise<boolean> {
     const creds = getCredentials()
-    if (!creds || !shouldRefreshToken(creds)) return
+    if (!creds) return false
+    if (!shouldRefreshToken(creds)) return true
 
     try {
       const response = await fetch(`${this.platformUrl}/api/auth/device/refresh`, {
@@ -109,14 +117,85 @@ export class PlatformConnection {
           token: data.accessToken,
           lastRefreshedAt: new Date().toISOString()
         })
-      } else {
-        console.warn('[Platform] Token refresh failed, will retry later')
+        return true
+      }
+      if (response.status === 401 || response.status === 403) {
+        console.warn(`[Platform] Token refresh failed — auth is expired (${response.status}). Run \`mstro login --force\`.`)
+        this.notifyAuthExpired()
+        return false
       }
+      console.warn(`[Platform] Token refresh failed with status ${response.status}, will retry later`)
+      return true
     } catch (err) {
       console.warn('[Platform] Token refresh error:', err)
+      return true
     }
   }
 
+  /**
+   * Verify the current token against the platform. A rejection (401/403)
+   * means the token is permanently invalid (revoked, signing-key rotation,
+   * account deleted); the caller should stop looping reconnects and tell
+   * the user to run `mstro login --force`.
+   *
+   * Returns `true` when the token is valid or the verification endpoint
+   * is unreachable (we prefer false negatives to false positives — a
+   * network blip shouldn't force a re-login).
+   */
+  private async verifyToken(): Promise<boolean> {
+    const creds = getCredentials()
+    if (!creds?.token) return false
+    try {
+      const response = await fetch(`${this.platformUrl}/api/auth/device/verify`, {
+        method: 'POST',
+        headers: { 'Authorization': `Bearer ${creds.token}` },
+      })
+      if (response.status === 401 || response.status === 403) {
+        console.warn(`[Platform] Token verify rejected (${response.status}) — auth is expired.`)
+        return false
+      }
+      return true
+    } catch {
+      // Network error: treat as "probably valid" so a flaky connection
+      // doesn't force users to re-login. The WebSocket open itself will
+      // catch a truly bad token via the 4001 path.
+      return true
+    }
+  }
+
+  /**
+   * Surface an auth-expired condition to any paired web clients.
+   *
+   * Two cooperating paths deliver this signal — either alone is enough,
+   * both together cover every timing edge:
+   *
+   *   1. **CLI-initiated (this method):** we detected a 401 from the
+   *      `/refresh` or `/verify` endpoint *while the relay socket is
+   *      still open*. `this.send` pushes the message upstream so the
+   *      server relays it to paired webs before we intentionally close.
+   *      A no-op if the socket is already closed.
+   *
+   *   2. **Server-initiated:** when the platform closes a CLI socket
+   *      with 4001 or 4008, `handleAuthClose` in `clientHandlers.ts`
+   *      broadcasts the same `clientAuthExpired` to paired webs. This
+   *      covers the cases where the CLI never had a chance to detect
+   *      the rejection itself (e.g. token revoked while the socket was
+   *      idle, server-side token rotation).
+   *
+   * IMPORTANT: never call `this.callbacks.onRelayedMessage` here —
+   * that callback feeds INCOMING web→CLI requests into the local handler,
+   * which would treat `clientAuthExpired` as an unknown inbound request.
+   */
+  private notifyAuthExpired(): void {
+    this.send({
+      type: 'clientAuthExpired',
+      data: {
+        connectionId: this.connectionId,
+        message: 'The CLI\'s device token is invalid — run `mstro login --force` on the machine.',
+      },
+    })
+  }
+
   private startTokenRefreshCheck(): void {
     this.tokenRefreshInterval = setInterval(() => {
       this.maybeRefreshToken()
@@ -162,39 +241,15 @@ export class PlatformConnection {
 
   connect(): void {
     this.isIntentionallyClosed = false
-    const name = basename(this.workingDirectory)
-    const machineHostname = hostname()
-    const clientId = getClientId()
-    const machineId = getMachineIdentifier()
-    const nodeVersion = process.version
-    const osType = type().toLowerCase()
-    const cpuArch = arch()
-
-    const credentials = getCredentials()
-    const authToken = credentials?.token
 
+    const authToken = getCredentials()?.token
     if (!authToken) {
       console.error('\n❌ Not logged in. Run `mstro login` first.\n')
       this.callbacks.onError?.('Not logged in - run `mstro login` first')
       return
     }
 
-    const params = new URLSearchParams({
-      name,
-      workingDirectory: this.workingDirectory,
-      machineHostname,
-      clientId,
-      machineId,
-      nodeVersion,
-      osType,
-      cpuArch,
-      cliVersion: CLI_VERSION,
-      capabilities: JSON.stringify({}),
-      startedAt: this.startedAt,
-    })
-
-    const wsUrl = `${this.platformUrl.replace(/^http/, 'ws')}/ws/client?${params}`
-
+    const wsUrl = this.buildConnectionUrl()
     try {
       this.ws = new WebSocketImpl(wsUrl)
     } catch (err) {
@@ -205,7 +260,47 @@ export class PlatformConnection {
       return
     }
 
-    const connectionTimeout = setTimeout(() => {
+    const connectionTimeout = this.startConnectionTimeout()
+    this.attachSocketHandlers(this.ws, authToken, connectionTimeout)
+    this.maybeVerifyTokenInParallel()
+  }
+
+  /**
+   * Best-effort token verification, fired in parallel with the socket
+   * open so a slow verify endpoint never delays reconnect.
+   *
+   * Only runs when the token is stale enough that we'd be about to
+   * refresh anyway — keeps the hot path free of an extra network call.
+   * A truly-revoked token that slips past this check still hits 4001
+   * on the WebSocket, which also triggers `notifyAuthExpired`.
+   */
+  private maybeVerifyTokenInParallel(): void {
+    const creds = getCredentials()
+    if (!creds || !shouldRefreshToken(creds)) return
+    this.verifyToken().then((valid) => {
+      if (!valid) this.notifyAuthExpired()
+    }).catch(() => { /* network error — rely on 4001 close path */ })
+  }
+
+  private buildConnectionUrl(): string {
+    const params = new URLSearchParams({
+      name: basename(this.workingDirectory),
+      workingDirectory: this.workingDirectory,
+      machineHostname: hostname(),
+      clientId: getClientId(),
+      machineId: getMachineIdentifier(),
+      nodeVersion: process.version,
+      osType: type().toLowerCase(),
+      cpuArch: arch(),
+      cliVersion: CLI_VERSION,
+      capabilities: JSON.stringify({}),
+      startedAt: this.startedAt,
+    })
+    return `${this.platformUrl.replace(/^http/, 'ws')}/ws/client?${params}`
+  }
+
+  private startConnectionTimeout(): ReturnType<typeof setTimeout> {
+    return setTimeout(() => {
       const state = this.ws?.readyState
       if (this.ws && (state === 0 || state === undefined)) {
         console.error('\n❌ Connection timeout. The platform may have rejected your credentials.')
@@ -214,55 +309,65 @@ export class PlatformConnection {
         this.callbacks.onError?.('Connection timeout - run `mstro login --force`')
       }
     }, 10000)
+  }
 
-    this.ws.onopen = () => {
+  private attachSocketHandlers(
+    ws: WebSocket,
+    authToken: string,
+    connectionTimeout: ReturnType<typeof setTimeout>,
+  ): void {
+    ws.onopen = () => {
       clearTimeout(connectionTimeout)
-      this.ws!.send(JSON.stringify({ type: 'auth', token: authToken }))
+      ws.send(JSON.stringify({ type: 'auth', token: authToken }))
       this.maybeRefreshToken()
       this.startTokenRefreshCheck()
       this.reconnectAttempts = 0
       trackEvent(AnalyticsEvents.PLATFORM_CONNECTED)
     }
 
-    this.ws.onmessage = (event) => {
+    ws.onmessage = (event) => {
       try {
-        const message = JSON.parse(event.data.toString())
-        this.handleMessage(message)
+        this.handleMessage(JSON.parse(event.data.toString()))
       } catch (err) {
         console.error('Failed to parse platform message:', err)
       }
     }
 
-    this.ws.onclose = (event) => {
+    ws.onclose = (event) => {
       clearTimeout(connectionTimeout)
-      this.stopHeartbeat()
-      this.isConnected = false
-
-      if (!this.isIntentionallyClosed) {
-        const isAuthFailure = event.code === 4001 ||
-          event.reason?.includes('Unauthorized') ||
-          (event.code === 1006 && !this.everConnected)
-
-        if (isAuthFailure) {
-          console.error('\n❌ Authentication failed. Your device token may be invalid or expired.')
-          console.error('   Run `mstro login --force` to re-authenticate.\n')
-          this.callbacks.onError?.('Authentication failed - run `mstro login --force`')
-          return
-        }
-
-        console.log('Disconnected, reconnecting...')
-        this.callbacks.onDisconnected?.()
-        trackEvent(AnalyticsEvents.PLATFORM_DISCONNECTED)
-        this.scheduleReconnect()
-      }
+      this.handleSocketClose(event)
     }
 
-    this.ws.onerror = () => {
+    ws.onerror = () => {
       clearTimeout(connectionTimeout)
       // onclose will be called after this
     }
   }
 
+  private handleSocketClose(event: CloseEvent): void {
+    this.stopHeartbeat()
+    this.isConnected = false
+
+    if (this.isIntentionallyClosed) return
+
+    const isAuthFailure = event.code === 4001 ||
+      event.reason?.includes('Unauthorized') ||
+      (event.code === 1006 && !this.everConnected)
+
+    if (isAuthFailure) {
+      console.error('\n❌ Authentication failed. Your device token may be invalid or expired.')
+      console.error('   Run `mstro login --force` to re-authenticate.\n')
+      this.notifyAuthExpired()
+      this.callbacks.onError?.('Authentication failed - run `mstro login --force`')
+      return
+    }
+
+    console.log('Disconnected, reconnecting...')
+    this.callbacks.onDisconnected?.()
+    trackEvent(AnalyticsEvents.PLATFORM_DISCONNECTED)
+    this.scheduleReconnect()
+  }
+
   private handleMessage(message: Record<string, unknown>): void {
     switch (message.type) {
       case 'paired':

package/server/services/websocket/file-download-handler.ts

@@ -0,0 +1,191 @@
+// Copyright (c) 2025-present Mstro, Inc. All rights reserved.
+// Licensed under the MIT License. See LICENSE file for details.
+
+/**
+ * Chunked File Download Handler
+ *
+ * Streams files to the web client as a sequence of WebSocket chunk messages.
+ * Mirrors the chunked upload path in reverse. Used for large binary files
+ * (images, PDFs) where a single base64-in-JSON `fileContent` message would
+ * exceed the relay's per-message cap or block the event loop during encoding.
+ *
+ * Chunk sizing: we emit 192 KB of raw bytes per chunk, which base64-encodes
+ * to ~256 KB — comfortably under the relay's 16 MB per-message limit even
+ * with JSON envelope overhead.
+ */
+
+import { createReadStream, existsSync, type ReadStream, statSync } from 'node:fs';
+import { basename, resolve, sep } from 'node:path';
+import { isBinaryFile, isPathInSafeLocation } from './file-utils.js';
+import type { WebSocketResponse, WSContext } from './types.js';
+
+const CHUNK_RAW_BYTES = 192 * 1024; // ~256 KB once base64-encoded
+const MAX_DOWNLOAD_SIZE = 50 * 1024 * 1024;
+const IDLE_TIMEOUT_MS = 120_000;
+
+interface DownloadState {
+  downloadId: string;
+  stream: ReadStream;
+  cancelled: boolean;
+  lastActivity: number;
+}
+
+function getMimeType(fullPath: string): string {
+  const ext = fullPath.toLowerCase().split('.').pop() || '';
+  if (ext === 'svg') return 'image/svg+xml';
+  if (ext === 'jpg' || ext === 'jpeg') return 'image/jpeg';
+  if (ext === 'pdf') return 'application/pdf';
+  if (['png', 'gif', 'webp', 'bmp', 'tiff', 'ico'].includes(ext)) return `image/${ext}`;
+  return 'application/octet-stream';
+}
+
+export class FileDownloadHandler {
+  private active = new Map<string, DownloadState>();
+  private cleanupInterval: ReturnType<typeof setInterval>;
+
+  constructor(private workingDir: string) {
+    this.cleanupInterval = setInterval(() => this.cleanupStale(), 30_000);
+  }
+
+  handleDownloadStart(
+    ws: WSContext,
+    send: (ws: WSContext, response: WebSocketResponse) => void,
+    tabId: string,
+    data: { downloadId: string; filePath: string },
+  ): void {
+    const { downloadId, filePath } = data;
+    const sendError = (error: string) => send(ws, {
+      type: 'fileDownloadError' as WebSocketResponse['type'],
+      tabId,
+      data: { downloadId, error },
+    });
+
+    try {
+      const fullPath = filePath.startsWith('/') ? filePath : resolve(this.workingDir, filePath);
+      const normalized = resolve(fullPath);
+      const normalizedWorkingDir = resolve(this.workingDir);
+
+      // Sandbox: must be under workingDir OR a known safe location (matches readFileContent)
+      const withinDir = normalized === normalizedWorkingDir
+        || normalized.startsWith(normalizedWorkingDir + sep);
+      if (!withinDir && !isPathInSafeLocation(normalized)) {
+        sendError('Access denied: path outside allowed locations');
+        return;
+      }
+      if (!existsSync(normalized)) {
+        sendError('File not found');
+        return;
+      }
+
+      const stats = statSync(normalized);
+      if (stats.isDirectory()) {
+        sendError('Path is a directory');
+        return;
+      }
+      if (stats.size > MAX_DOWNLOAD_SIZE) {
+        sendError(`File too large: ${(stats.size / 1024 / 1024).toFixed(1)}MB exceeds ${MAX_DOWNLOAD_SIZE / 1024 / 1024}MB limit`);
+        return;
+      }
+
+      const totalChunks = Math.max(1, Math.ceil(stats.size / CHUNK_RAW_BYTES));
+      const fileName = basename(normalized);
+      const isImg = isBinaryFile(normalized);
+
+      send(ws, {
+        type: 'fileDownloadReady' as WebSocketResponse['type'],
+        tabId,
+        data: {
+          downloadId,
+          filePath,
+          fileName,
+          size: stats.size,
+          mimeType: getMimeType(normalized),
+          isImage: isImg,
+          totalChunks,
+          modifiedAt: stats.mtime.toISOString(),
+        },
+      });
+
+      const stream = createReadStream(normalized, { highWaterMark: CHUNK_RAW_BYTES });
+      const state: DownloadState = {
+        downloadId,
+        stream,
+        cancelled: false,
+        lastActivity: Date.now(),
+      };
+      this.active.set(downloadId, state);
+
+      let chunkIndex = 0;
+      stream.on('data', (buf: Buffer | string) => {
+        if (state.cancelled) return;
+        // Node may deliver buffers larger than highWaterMark on stream edges;
+        // slice back down so each WS frame stays predictable.
+        const chunk = typeof buf === 'string' ? Buffer.from(buf) : buf;
+        for (let off = 0; off < chunk.length; off += CHUNK_RAW_BYTES) {
+          const slice = chunk.subarray(off, Math.min(off + CHUNK_RAW_BYTES, chunk.length));
+          send(ws, {
+            type: 'fileDownloadChunk' as WebSocketResponse['type'],
+            tabId,
+            data: {
+              downloadId,
+              chunkIndex: chunkIndex++,
+              content: slice.toString('base64'),
+            },
+          });
+        }
+        state.lastActivity = Date.now();
+      });
+
+      stream.on('end', () => {
+        if (state.cancelled) return;
+        send(ws, {
+          type: 'fileDownloadComplete' as WebSocketResponse['type'],
+          tabId,
+          data: { downloadId },
+        });
+        this.active.delete(downloadId);
+      });
+
+      stream.on('error', (err) => {
+        sendError(`Read failed: ${err.message}`);
+        this.active.delete(downloadId);
+      });
+    } catch (err) {
+      sendError(err instanceof Error ? err.message : String(err));
+    }
+  }
+
+  handleDownloadCancel(
+    _ws: WSContext,
+    _send: (ws: WSContext, response: WebSocketResponse) => void,
+    _tabId: string,
+    data: { downloadId: string },
+  ): void {
+    const state = this.active.get(data.downloadId);
+    if (!state) return;
+    state.cancelled = true;
+    state.stream.destroy();
+    this.active.delete(data.downloadId);
+  }
+
+  private cleanupStale(): void {
+    const now = Date.now();
+    for (const [id, state] of this.active) {
+      if (now - state.lastActivity > IDLE_TIMEOUT_MS) {
+        console.warn(`[FileDownloadHandler] Download ${id} idle, cleaning up`);
+        state.cancelled = true;
+        state.stream.destroy();
+        this.active.delete(id);
+      }
+    }
+  }
+
+  destroy(): void {
+    clearInterval(this.cleanupInterval);
+    for (const state of this.active.values()) {
+      state.cancelled = true;
+      state.stream.destroy();
+    }
+    this.active.clear();
+  }
+}

package/server/services/websocket/git-branch-handlers.ts

@@ -2,6 +2,7 @@
 // Licensed under the MIT License. See LICENSE file for details.
 
 import { executeGitCommand, sendGitError } from './git-utils.js';
+import { findWorktreePathForBranch, handleTabWorktreeSwitch } from './git-worktree-handlers.js';
 import type { HandlerContext } from './handler-context.js';
 import type { GitBranchEntry, WebSocketMessage, WSContext } from './types.js';
 
@@ -40,7 +41,28 @@ export async function handleGitListBranches(ctx: HandlerContext, ws: WSContext,
   }
 }
 
-export async function handleGitCheckout(ctx: HandlerContext, ws: WSContext, msg: WebSocketMessage, tabId: string, workingDir: string): Promise<void> {
+/**
+ * If `branch` is already checked out in a worktree other than `workingDir`, redirect the tab
+ * there via the worktree-switch flow and return true. Git refuses `checkout` in this case, so
+ * treating it as a view change is both correct and the only thing that works.
+ */
+async function redirectToWorktreeIfBranchCheckedOut(
+  ctx: HandlerContext, ws: WSContext,
+  tabId: string, branch: string, workingDir: string, rootWorkingDir: string,
+): Promise<boolean> {
+  const wtListResult = await executeGitCommand(['worktree', 'list', '--porcelain'], workingDir);
+  if (wtListResult.exitCode !== 0) return false;
+  const existingWt = findWorktreePathForBranch(wtListResult.stdout, branch);
+  if (!existingWt || existingWt === workingDir) return false;
+  await handleTabWorktreeSwitch(
+    ctx, ws,
+    { type: 'tabWorktreeSwitch', tabId, data: { tabId, worktreePath: existingWt } },
+    tabId, rootWorkingDir,
+  );
+  return true;
+}
+
+export async function handleGitCheckout(ctx: HandlerContext, ws: WSContext, msg: WebSocketMessage, tabId: string, workingDir: string, rootWorkingDir: string): Promise<void> {
   try {
     const { branch, create, startPoint } = msg.data || {};
     if (!branch) {
@@ -48,6 +70,11 @@ export async function handleGitCheckout(ctx: HandlerContext, ws: WSContext, msg:
       return;
     }
 
+    // Skip the worktree redirect for `create` — a name collision there is a real user error.
+    if (!create && await redirectToWorktreeIfBranchCheckedOut(ctx, ws, tabId, branch, workingDir, rootWorkingDir)) {
+      return;
+    }
+
     const statusResult = await executeGitCommand(['status', '--porcelain'], workingDir);
     if (statusResult.stdout.trim()) {
       ctx.send(ws, { type: 'gitError', tabId, data: { error: 'Commit or stash changes before switching branches' } });

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

@@ -53,7 +53,7 @@ export async function handleGitMessage(ctx: HandlerContext, ws: WSContext, msg:
     gitDiscoverRepos: () => handleGitDiscoverRepos(ctx, ws, tabId, workingDir),
     gitSetDirectory: () => handleGitSetDirectory(ctx, ws, msg, tabId, workingDir),
     gitListBranches: () => handleGitListBranches(ctx, ws, tabId, gitDir),
-    gitCheckout: () => handleGitCheckout(ctx, ws, msg, tabId, gitDir),
+    gitCheckout: () => handleGitCheckout(ctx, ws, msg, tabId, gitDir, workingDir),
     gitCreateBranch: () => handleGitCreateBranch(ctx, ws, msg, tabId, gitDir),
     gitDeleteBranch: () => handleGitDeleteBranch(ctx, ws, msg, tabId, gitDir),
     gitDiff: () => handleGitDiff(ctx, ws, msg, tabId, gitDir),

package/server/services/websocket/git-worktree-handlers.ts

@@ -6,6 +6,7 @@ import { dirname, join } from 'node:path';
 import { resolvePmDir } from '../plan/parser.js';
 import type { Workspace } from '../plan/types.js';
 import { executeGitCommand, handleGitStatus, spawnWithOutput } from './git-handlers.js';
+import { handleGitLog } from './git-log-handlers.js';
 import type { HandlerContext } from './handler-context.js';
 import type { WebSocketMessage, WorktreeInfo, WSContext } from './types.js';
 
@@ -201,7 +202,7 @@ async function handleGitWorktreeRemove(ctx: HandlerContext, ws: WSContext, msg:
   }
 }
 
-async function handleTabWorktreeSwitch(ctx: HandlerContext, ws: WSContext, msg: WebSocketMessage, tabId: string, workingDir: string): Promise<void> {
+export async function handleTabWorktreeSwitch(ctx: HandlerContext, ws: WSContext, msg: WebSocketMessage, tabId: string, workingDir: string): Promise<void> {
   try {
     const { tabId: targetTabId, worktreePath } = msg.data || {};
     const resolvedTabId = targetTabId || tabId;
@@ -214,7 +215,7 @@ async function handleTabWorktreeSwitch(ctx: HandlerContext, ws: WSContext, msg:
         persistBoardWorktree(workingDir, resolvedTabId, null, null);
       }
       ctx.send(ws, { type: 'tabWorktreeSwitched', tabId: resolvedTabId, data: { tabId: resolvedTabId, worktreePath: null, branch: null } });
-      handleGitStatus(ctx, ws, resolvedTabId, workingDir);
+      refreshScopeAfterWorktreeSwitch(ctx, ws, resolvedTabId, workingDir);
       return;
     }
 
@@ -229,12 +230,38 @@ async function handleTabWorktreeSwitch(ctx: HandlerContext, ws: WSContext, msg:
     }
 
     ctx.send(ws, { type: 'tabWorktreeSwitched', tabId: resolvedTabId, data: { tabId: resolvedTabId, worktreePath, branch } });
-    handleGitStatus(ctx, ws, resolvedTabId, worktreePath);
+    refreshScopeAfterWorktreeSwitch(ctx, ws, resolvedTabId, worktreePath);
   } catch (error: unknown) {
     ctx.send(ws, { type: 'gitError', tabId, data: { error: error instanceof Error ? error.message : String(error) } });
   }
 }
 
+/**
+ * After a worktree switch, re-fetch everything that's worktree-specific so
+ * the client sees a complete, consistent view of the newly-selected workspace
+ * from a single `tabWorktreeSwitched` event. Keeping the refresh on the
+ * server side means the client has one signal to react to instead of having
+ * to orchestrate status/log/... fetches itself.
+ *
+ * Branches and the worktree list are NOT re-fetched: they're repo-wide, not
+ * worktree-specific.
+ *
+ * Fire-and-forget: the switch itself has already been acknowledged via
+ * `tabWorktreeSwitched`. `handleGitStatus` and `handleGitLog` each own their
+ * own error handling (they send `gitError` scoped to the correct tabId).
+ * Awaiting here would let any unexpected throw escape into the caller's
+ * outer try/catch and produce a misleading `gitError` on the original
+ * dispatch tabId after success has already been signalled.
+ */
+function refreshScopeAfterWorktreeSwitch(ctx: HandlerContext, ws: WSContext, tabId: string, gitDir: string): void {
+  (async () => {
+    await handleGitStatus(ctx, ws, tabId, gitDir);
+    await handleGitLog(ctx, ws, { type: 'gitLog', tabId, data: { limit: 20 } }, tabId, gitDir);
+  })().catch((error: unknown) => {
+    console.error('[handleTabWorktreeSwitch] scope refresh failed:', error);
+  });
+}
+
 async function pushWithUpstreamRetry(
   worktreePath: string,
   pushRemote: string,
@@ -445,7 +472,7 @@ async function cleanupAfterMerge(
   return { warnings, removedWorktreePath };
 }
 
-function findWorktreePathForBranch(porcelainOutput: string, branchName: string): string | null {
+export function findWorktreePathForBranch(porcelainOutput: string, branchName: string): string | null {
   let currentWtPath = '';
   const fullRef = `refs/heads/${branchName}`;
   for (const line of porcelainOutput.split('\n')) {

package/server/services/websocket/handler-context.ts

@@ -6,8 +6,10 @@ import type { ImprovisationSessionManager } from '../../cli/improvisation-sessio
 import type { AutocompleteService } from './autocomplete.js';
 import type { FileUploadHandler } from './file-upload-handler.js';
 import type { GitHeadWatcher } from './git-head-watcher.js';
+import type { MsgIdTracker } from './msg-id-tracker.js';
 import type { SessionRegistry } from './session-registry.js';
 import type { SkillsWatcher } from './skill-watcher.js';
+import type { TabEventBufferRegistry } from './tab-event-buffer.js';
 import type { WebSocketResponse, WSContext } from './types.js';
 
 export interface UsageReport {
@@ -37,6 +39,19 @@ export interface HandlerContext {
   fileUploadHandler: FileUploadHandler | null;
   gitHeadWatcher: GitHeadWatcher | null;
   skillsWatcher: SkillsWatcher | null;
+  /**
+   * Per-tab replay buffer for tab-scoped broadcasts. Populated by
+   * `broadcastTabEvent` (see `tab-broadcast.ts`) so a web client rejoining a
+   * tab after a reconnect can request replay of anything it missed during
+   * the transport gap. See `tab-event-buffer.ts`.
+   */
+  tabEventBuffers: TabEventBufferRegistry;
+  /**
+   * Idempotency tracker for `execute` `msgId`s. Lets the web replay the
+   * same prompt across reconnects without causing double execution — the
+   * CLI still acks, but skips running the prompt a second time.
+   */
+  msgIdTracker: MsgIdTracker;
 
   // Registry access
   getRegistry(workingDir: string): SessionRegistry;