mstro-app 0.5.0 → 0.5.5

package/server/services/websocket/git-worktree-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 { existsSync, readFileSync, writeFileSync } from 'node:fs';
 import { dirname, join } from 'node:path';
@@ -7,8 +6,21 @@ 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 { parseGitStatus } from './git-utils.js';
 import type { HandlerContext } from './handler-context.js';
-import type { WebSocketMessage, WorktreeInfo, WSContext } from './types.js';
+import type { GitFileStatus, WebSocketMessage, WorktreeInfo, WSContext } from './types.js';
+
+/**
+ * A file in the merge target's working tree whose uncommitted state would be
+ * lost if the merge proceeds. Used to drive the merge dialog's blocker state
+ * before the merge attempt and to translate the post-flight git error if a
+ * race lets one slip through.
+ */
+interface MergeBlocker {
+  path: string;
+  status: GitFileStatus['status'];
+  staged: boolean;
+}
 
 function persistBoardWorktree(workingDir: string, boardId: string, worktreePath: string | null, branch: string | null): void {
   const pmDir = resolvePmDir(workingDir);
@@ -44,6 +56,8 @@ export async function handleGitWorktreeMessage(ctx: HandlerContext, ws: WSContex
     gitWorktreeMerge: () => handleGitWorktreeMerge(ctx, ws, msg, tabId, gitDir),
     gitMergeAbort: () => handleGitMergeAbort(ctx, ws, tabId, gitDir),
     gitMergeComplete: () => handleGitMergeComplete(ctx, ws, msg, tabId, gitDir),
+    gitMergeStashPop: () => handleGitMergeStashPop(ctx, ws, msg, tabId, gitDir),
+    gitMergeDiscardBlockers: () => handleGitMergeDiscardBlockers(ctx, ws, msg, tabId, gitDir),
   };
   await handlers[msg.type]?.();
 }
@@ -339,6 +353,64 @@ async function handleGitWorktreeCreatePR(ctx: HandlerContext, ws: WSContext, msg
   }
 }
 
+/**
+ * Files in the target worktree's working tree whose dirty state intersects
+ * the set of files the merge would touch. These are the rows that drive the
+ * merge dialog's "uncommitted changes on <target>" blocker UI — surfacing
+ * them preflight prevents the user from ever hitting git's raw "would be
+ * overwritten" error.
+ *
+ * Detection strategy:
+ *   - `git status --porcelain=v1` on the target's worktree → all dirty paths
+ *   - `git diff --name-only target..source` → all paths the merge would touch
+ *   - intersection = blockers
+ *
+ * Untracked files are included via the porcelain output (they collide with
+ * incoming additions of the same path). Files that are dirty but outside the
+ * merge's diff are NOT blockers — git would carry them through cleanly.
+ */
+async function detectMergeBlockers(
+  targetWorktreePath: string,
+  sourceBranch: string,
+  targetBranch: string,
+): Promise<MergeBlocker[]> {
+  const statusResult = await executeGitCommand(['status', '--porcelain=v1'], targetWorktreePath);
+  if (statusResult.exitCode !== 0) return [];
+  const { staged, unstaged, untracked } = parseGitStatus(statusResult.stdout);
+
+  const diffResult = await executeGitCommand(
+    ['diff', '--name-only', `${targetBranch}..${sourceBranch}`],
+    targetWorktreePath,
+  );
+  if (diffResult.exitCode !== 0) return [];
+  const mergeTouches = new Set(
+    diffResult.stdout.split('\n').map(s => s.trim()).filter(Boolean),
+  );
+  if (mergeTouches.size === 0) return [];
+
+  // Prefer the worktree (unstaged) status when both index and worktree are
+  // dirty — that's what the user would lose. Fall back to staged, then
+  // untracked. Order in the result list groups deletions last so the UI can
+  // surface them where users expect.
+  const seen = new Map<string, MergeBlocker>();
+  const consider = (entries: GitFileStatus[]) => {
+    for (const entry of entries) {
+      if (!mergeTouches.has(entry.path)) continue;
+      if (seen.has(entry.path)) continue;
+      seen.set(entry.path, { path: entry.path, status: entry.status, staged: entry.staged });
+    }
+  };
+  consider(unstaged);
+  consider(staged);
+  consider(untracked);
+
+  return Array.from(seen.values()).sort((a, b) => {
+    if (a.status === 'D' && b.status !== 'D') return 1;
+    if (a.status !== 'D' && b.status === 'D') return -1;
+    return a.path.localeCompare(b.path);
+  });
+}
+
 async function handleGitMergePreview(ctx: HandlerContext, ws: WSContext, msg: WebSocketMessage, tabId: string, workingDir: string): Promise<void> {
   try {
     const { sourceBranch, targetBranch } = msg.data || {};
@@ -374,10 +446,30 @@ async function handleGitMergePreview(ctx: HandlerContext, ws: WSContext, msg: We
         return { hash: hash.trim(), message: rest.join('|').trim() };
       });
 
+    // The merge always lands on the main worktree currently checked out to
+    // the target branch. If main isn't on `targetBranch` we can't preflight
+    // blockers (the dirty state wouldn't be the relevant one), so skip the
+    // check and let the post-flight handler surface the branch-mismatch
+    // error like before.
+    const mainPath = await resolveMainWorktreePath(workingDir);
+    const mainBranchResult = await executeGitCommand(['rev-parse', '--abbrev-ref', 'HEAD'], mainPath);
+    const mainOnTarget = mainBranchResult.stdout.trim() === targetBranch;
+    const blockers = mainOnTarget
+      ? await detectMergeBlockers(mainPath, sourceBranch, targetBranch)
+      : [];
+
     ctx.send(ws, {
       type: 'gitMergePreviewResult',
       tabId,
-      data: { clean, conflicts, stat, commits, ahead: commits.length },
+      data: {
+        clean,
+        conflicts,
+        stat,
+        commits,
+        ahead: commits.length,
+        targetWorktreePath: mainPath,
+        targetWorktreeBlockers: blockers,
+      },
     });
   } catch (error: unknown) {
     ctx.send(ws, { type: 'gitError', tabId, data: { error: error instanceof Error ? error.message : String(error) } });
@@ -482,9 +574,103 @@ export function findWorktreePathForBranch(porcelainOutput: string, branchName: s
   return null;
 }
 
+/**
+ * Parse a git stderr buffer for the "your local changes / untracked working
+ * tree files would be overwritten by merge" message. Returned paths feed the
+ * web client's blocker UI when a merge slips through preflight (race against
+ * a teammate's auto-formatter, stale status, etc.).
+ */
+function parseOverwritePaths(stderr: string): string[] {
+  const lines = stderr.split('\n');
+  const headerIdx = lines.findIndex(l =>
+    /your local changes to the following files would be overwritten/i.test(l) ||
+    /untracked working tree files would be overwritten/i.test(l),
+  );
+  if (headerIdx < 0) return [];
+  const paths: string[] = [];
+  for (let i = headerIdx + 1; i < lines.length; i++) {
+    const line = lines[i];
+    const trimmed = line.trim();
+    if (!trimmed) continue;
+    if (/^(merge with strategy|aborting|please commit)/i.test(trimmed)) break;
+    // Git indents each path with a tab; tolerate spaces too.
+    if (/^[\t ]/.test(line)) {
+      paths.push(trimmed);
+    }
+  }
+  return paths;
+}
+
+const STASH_MESSAGE_TAG = 'mstro:pre-merge';
+
+async function pushMergeStash(targetWorktreePath: string, sourceBranch: string, targetBranch: string): Promise<{ ref: string; sha: string; message: string } | null> {
+  const message = `${STASH_MESSAGE_TAG} ${targetBranch} <- ${sourceBranch} @ ${new Date().toISOString()}`;
+  const result = await executeGitCommand(['stash', 'push', '-u', '-m', message], targetWorktreePath);
+  if (result.exitCode !== 0) return null;
+  // "No local changes to save" exits 0 but does not push a stash; detect by
+  // checking whether stash@{0}'s message matches what we just wrote.
+  const top = await executeGitCommand(['stash', 'list', '-n', '1', '--format=%H%x09%gs'], targetWorktreePath);
+  if (top.exitCode !== 0) return null;
+  const [sha, ...rest] = top.stdout.trim().split('\t');
+  const stashedMsg = rest.join('\t');
+  if (!sha || !stashedMsg.includes(STASH_MESSAGE_TAG)) return null;
+  return { ref: 'stash@{0}', sha, message };
+}
+
+async function popMergeStashBySha(targetWorktreePath: string, sha: string): Promise<{ exitCode: number; error?: string }> {
+  const list = await executeGitCommand(['stash', 'list', '--format=%gd%x09%H'], targetWorktreePath);
+  if (list.exitCode !== 0) return { exitCode: list.exitCode, error: list.stderr || 'Failed to read stash list' };
+  const ref = list.stdout.split('\n').map(l => l.split('\t')).find(([, h]) => h === sha)?.[0];
+  if (!ref) return { exitCode: 1, error: 'Stash no longer exists — it may have already been popped or dropped.' };
+  const pop = await executeGitCommand(['stash', 'pop', ref], targetWorktreePath);
+  return { exitCode: pop.exitCode, error: pop.exitCode !== 0 ? pop.stderr : undefined };
+}
+
+/**
+ * Decide what shape of merge-failure payload to send the client. Splits the
+ * three error modes — index conflict, target-worktree blocker, generic — out
+ * of the main handler so each is a self-contained branch.
+ */
+async function buildMergeFailurePayload(
+  mainPath: string,
+  sourceBranch: string,
+  targetBranch: string,
+  mergeError: string | undefined,
+): Promise<Record<string, unknown>> {
+  const conflictFiles = await detectMergeConflicts(mainPath);
+  if (conflictFiles.length > 0) {
+    return { success: false, conflictFiles, targetWorktreePath: mainPath };
+  }
+  const overwritten = parseOverwritePaths(mergeError || '');
+  if (overwritten.length > 0) {
+    const blockers = await detectMergeBlockers(mainPath, sourceBranch, targetBranch);
+    const targetWorktreeBlockers: MergeBlocker[] = blockers.length > 0
+      ? blockers
+      : overwritten.map(p => ({ path: p, status: 'M' as const, staged: false }));
+    return { success: false, targetWorktreePath: mainPath, targetWorktreeBlockers };
+  }
+  return { success: false, error: mergeError || 'Merge failed', targetWorktreePath: mainPath };
+}
+
+function buildMergeSuccessPayload(
+  mainPath: string,
+  mergeCommit: string,
+  warnings: string[],
+  stash: { ref: string; sha: string; message: string } | null,
+): Record<string, unknown> {
+  const data: Record<string, unknown> = { success: true, mergeCommit, targetWorktreePath: mainPath };
+  if (warnings.length > 0) data.warnings = warnings;
+  if (stash) {
+    data.stashRef = stash.ref;
+    data.stashSha = stash.sha;
+    data.stashMessage = stash.message;
+  }
+  return data;
+}
+
 async function handleGitWorktreeMerge(ctx: HandlerContext, ws: WSContext, msg: WebSocketMessage, tabId: string, workingDir: string): Promise<void> {
   try {
-    const { sourceBranch, targetBranch, strategy, commitMessage, deleteWorktree, deleteBranch } = msg.data || {};
+    const { sourceBranch, targetBranch, strategy, commitMessage, deleteWorktree, deleteBranch, stashFirst } = msg.data || {};
     if (!sourceBranch || !targetBranch || !strategy) {
       ctx.send(ws, { type: 'gitError', tabId, data: { error: 'Source branch, target branch, and strategy are required' } });
       return;
@@ -494,40 +680,97 @@ async function handleGitWorktreeMerge(ctx: HandlerContext, ws: WSContext, msg: W
 
     const mainBranchResult = await executeGitCommand(['rev-parse', '--abbrev-ref', 'HEAD'], mainPath);
     if (mainBranchResult.stdout.trim() !== targetBranch) {
-      ctx.send(ws, { type: 'gitWorktreeMergeResult', tabId, data: { success: false, error: `Switch the main worktree to "${targetBranch}" before merging` } });
+      ctx.send(ws, { type: 'gitWorktreeMergeResult', tabId, data: { success: false, error: `Switch the main worktree to "${targetBranch}" before merging`, targetWorktreePath: mainPath } });
       return;
     }
 
-    const headBefore = await executeGitCommand(['rev-parse', 'HEAD'], mainPath);
+    // Stash first if requested. A no-op result (nothing to stash, e.g. user
+    // already cleaned up between preflight and merge) is fine — we still
+    // proceed with the merge.
+    const stash = stashFirst ? await pushMergeStash(mainPath, sourceBranch, targetBranch) : null;
 
+    const headBefore = await executeGitCommand(['rev-parse', 'HEAD'], mainPath);
     const mergeResult = await executeMergeStrategy(strategy, sourceBranch, commitMessage, mainPath);
+
     if (mergeResult.exitCode !== 0) {
-      const conflictFiles = await detectMergeConflicts(mainPath);
-      const data = conflictFiles.length > 0
-        ? { success: false, conflictFiles }
-        : { success: false, error: mergeResult.error || 'Merge failed' };
+      // Best-effort restore of the user's working tree before reporting.
+      // If pop conflicts, the stash stays around and the user can recover it
+      // manually — we still surface the original merge error.
+      if (stash) await popMergeStashBySha(mainPath, stash.sha).catch(() => undefined);
+      const data = await buildMergeFailurePayload(mainPath, sourceBranch, targetBranch, mergeResult.error);
       ctx.send(ws, { type: 'gitWorktreeMergeResult', tabId, data });
       return;
     }
 
     const headAfter = await executeGitCommand(['rev-parse', 'HEAD'], mainPath);
     if (headBefore.stdout.trim() === headAfter.stdout.trim()) {
-      ctx.send(ws, { type: 'gitWorktreeMergeResult', tabId, data: { success: false, error: `Already up to date — "${sourceBranch}" has no new commits to merge into "${targetBranch}"` } });
+      if (stash) await popMergeStashBySha(mainPath, stash.sha).catch(() => undefined);
+      ctx.send(ws, { type: 'gitWorktreeMergeResult', tabId, data: { success: false, error: `Already up to date — "${sourceBranch}" has no new commits to merge into "${targetBranch}"`, targetWorktreePath: mainPath } });
       return;
     }
 
     const commitHashResult = await executeGitCommand(['rev-parse', '--short', 'HEAD'], mainPath);
     const { warnings, removedWorktreePath } = await cleanupAfterMerge(mainPath, sourceBranch, strategy, !!deleteWorktree, !!deleteBranch);
+    if (removedWorktreePath) cleanupWorktreeReferences(ctx, workingDir, removedWorktreePath);
+
+    const data = buildMergeSuccessPayload(mainPath, commitHashResult.stdout.trim(), warnings, stash);
+    ctx.send(ws, { type: 'gitWorktreeMergeResult', tabId, data });
+  } catch (error: unknown) {
+    ctx.send(ws, { type: 'gitError', tabId, data: { error: error instanceof Error ? error.message : String(error) } });
+  }
+}
 
-    if (removedWorktreePath) {
-      cleanupWorktreeReferences(ctx, workingDir, removedWorktreePath);
+async function handleGitMergeStashPop(ctx: HandlerContext, ws: WSContext, msg: WebSocketMessage, tabId: string, workingDir: string): Promise<void> {
+  try {
+    const { stashSha, targetWorktreePath } = msg.data || {};
+    if (!stashSha) {
+      ctx.send(ws, { type: 'gitMergeStashPopped', tabId, data: { success: false, error: 'Missing stash reference' } });
+      return;
+    }
+    const path = targetWorktreePath || (await resolveMainWorktreePath(workingDir));
+    const result = await popMergeStashBySha(path, stashSha);
+    if (result.exitCode !== 0) {
+      ctx.send(ws, { type: 'gitMergeStashPopped', tabId, data: { success: false, error: result.error || 'Failed to pop stash', targetWorktreePath: path } });
+      return;
     }
+    ctx.send(ws, { type: 'gitMergeStashPopped', tabId, data: { success: true, targetWorktreePath: path } });
+    // Refresh status so the file explorer / git view reflects the restored changes.
+    handleGitStatus(ctx, ws, tabId, path);
+  } catch (error: unknown) {
+    ctx.send(ws, { type: 'gitError', tabId, data: { error: error instanceof Error ? error.message : String(error) } });
+  }
+}
 
-    const data: Record<string, unknown> = { success: true, mergeCommit: commitHashResult.stdout.trim() };
-    if (warnings.length > 0) {
-      data.warnings = warnings;
+async function handleGitMergeDiscardBlockers(ctx: HandlerContext, ws: WSContext, msg: WebSocketMessage, tabId: string, workingDir: string): Promise<void> {
+  try {
+    const { paths, targetWorktreePath } = msg.data || {};
+    if (!Array.isArray(paths) || paths.length === 0) {
+      ctx.send(ws, { type: 'gitMergeBlockersDiscarded', tabId, data: { success: false, error: 'No paths to discard' } });
+      return;
     }
-    ctx.send(ws, { type: 'gitWorktreeMergeResult', tabId, data });
+    const path = targetWorktreePath || (await resolveMainWorktreePath(workingDir));
+
+    // Restore tracked files (modifications, deletions, stages) from HEAD.
+    // `git checkout HEAD -- <paths>` overwrites both index and worktree, which
+    // is exactly the "discard" semantics the UI promised the user.
+    const checkoutResult = await executeGitCommand(['checkout', 'HEAD', '--', ...paths], path);
+    // Untracked files won't be touched by `checkout HEAD --` (git refuses with
+    // "did not match any file(s) known to git" when ALL paths are untracked,
+    // but mixed lists succeed for the tracked subset). Run `git clean -f` on
+    // the originally-supplied list to remove any untracked leftovers — git
+    // ignores anything that's already gone, so this is safe to run after.
+    const cleanResult = await executeGitCommand(['clean', '-f', '--', ...paths], path);
+
+    if (checkoutResult.exitCode !== 0 && cleanResult.exitCode !== 0) {
+      ctx.send(ws, {
+        type: 'gitMergeBlockersDiscarded',
+        tabId,
+        data: { success: false, error: checkoutResult.stderr || cleanResult.stderr || 'Failed to discard changes', targetWorktreePath: path },
+      });
+      return;
+    }
+    ctx.send(ws, { type: 'gitMergeBlockersDiscarded', tabId, data: { success: true, targetWorktreePath: path, paths } });
+    handleGitStatus(ctx, ws, tabId, path);
   } catch (error: unknown) {
     ctx.send(ws, { type: 'gitError', tabId, data: { error: error instanceof Error ? error.message : String(error) } });
   }

package/server/services/websocket/handler-context.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 { ChildProcess } from 'node:child_process';
 import type { ImprovisationSessionManager } from '../../cli/improvisation-session-manager.js';

package/server/services/websocket/handler.ts

@@ -1,5 +1,4 @@
 // Copyright (c) 2025-present Mstro, Inc. All rights reserved.
-// Licensed under the MIT License. See LICENSE file for details.
 
 /**
  * WebSocket Handler for Improvisation Sessions
@@ -13,6 +12,7 @@ import { existsSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs';
 import { homedir } from 'node:os';
 import { dirname, join } from 'node:path';
 import type { ImprovisationSessionManager } from '../../cli/improvisation-session-manager.js';
+import type { InstanceRegistry } from '../instances.js';
 import { captureException } from '../sentry.js';
 import { getPTYManager } from '../terminal/pty-manager.js';
 import { AutocompleteService } from './autocomplete.js';
@@ -31,7 +31,7 @@ import { generateNotificationSummary, handleGetSettings, handleUpdateSettings }
 import { handleListSkills } from './skill-handlers.js';
 import { SkillsWatcher } from './skill-watcher.js';
 import { TabEventBufferRegistry } from './tab-event-buffer.js';
-import { handleCreateTab, handleGetActiveTabs, handleMarkTabViewed, handleRemoveTab, handleReorderTabs, handleSyncTabMeta } from './tab-handlers.js';
+import { handleCreateTab, handleGetActiveTabs, handleMarkTabViewed, handleRemoveTab, handleReorderTabs, handleSetTabEngine, handleSyncTabMeta } from './tab-handlers.js';
 import { cleanupTerminalSubscribers, handleTerminalMessage } from './terminal-handlers.js';
 import type { FrecencyData, WebSocketMessage, WebSocketResponse, WSContext } from './types.js';
 
@@ -56,11 +56,14 @@ export class WebSocketImproviseHandler implements HandlerContext {
   skillsWatcher: SkillsWatcher | null = null;
   tabEventBuffers: TabEventBufferRegistry = new TabEventBufferRegistry();
   msgIdTracker: MsgIdTracker = new MsgIdTracker();
+  private instanceRegistry: InstanceRegistry | null;
+  private shutdownInProgress = false;
 
-  constructor() {
+  constructor(instanceRegistry: InstanceRegistry | null = null) {
     this.frecencyPath = join(homedir(), '.mstro', 'autocomplete-frecency.json');
     const frecencyData = this.loadFrecencyData();
     this.autocompleteService = new AutocompleteService(frecencyData);
+    this.instanceRegistry = instanceRegistry;
     process.on('exit', () => {
       if (this.frecencySaveTimer) {
         clearTimeout(this.frecencySaveTimer);
@@ -202,6 +205,9 @@ export class WebSocketImproviseHandler implements HandlerContext {
         return handleRemoveTab(this, ws, tabId, workingDir);
       case 'markTabViewed':
         return handleMarkTabViewed(this, ws, tabId, workingDir);
+      case 'setTabEngine':
+        if (permission === 'view') return;
+        return handleSetTabEngine(this, ws, msg, tabId, workingDir);
       case 'getSettings':
         return handleGetSettings(this, ws);
       case 'updateSettings':
@@ -209,6 +215,8 @@ export class WebSocketImproviseHandler implements HandlerContext {
         return handleUpdateSettings(this, ws, msg);
       case 'listSkills':
         return handleListSkills(this, ws, workingDir);
+      case 'shutdownInstance':
+        return this.handleShutdownInstance(ws, permission);
     }
 
     // Dispatch table lookup for domain handlers
@@ -235,7 +243,7 @@ export class WebSocketImproviseHandler implements HandlerContext {
       case 'git':        return handleGitMessage(this, ws, msg, tabId, workingDir);
       case 'quality':    return handleQualityMessage(this, ws, msg, tabId, workingDir, permission);
       case 'plan':       return handlePlanMessage(this, ws, msg, tabId, workingDir, permission);
-      case 'fileUpload': return this.handleFileUploadMessage(ws, msg, tabId, workingDir, permission);
+      case 'fileUpload': return this.handleFileUploadMessage(ws, msg, tabId, effectiveDir, permission);
       case 'fileDownload': return this.handleFileDownloadMessage(ws, msg, tabId, effectiveDir);
     }
   }
@@ -259,14 +267,14 @@ export class WebSocketImproviseHandler implements HandlerContext {
 
   private handleFileUploadMessage(ws: WSContext, msg: WebSocketMessage, tabId: string, workingDir: string, permission?: 'view'): void {
     if (!this.fileUploadHandler) {
-      this.fileUploadHandler = new FileUploadHandler(workingDir, this);
+      this.fileUploadHandler = new FileUploadHandler(this);
     }
     const handler = this.fileUploadHandler;
     const send = this.send.bind(this);
 
     switch (msg.type) {
       case 'fileUploadStart':
-        handler.handleUploadStart(ws, send, tabId, msg.data, permission);
+        handler.handleUploadStart(ws, send, tabId, msg.data, workingDir, permission);
         break;
       case 'fileUploadChunk':
         handler.handleUploadChunk(ws, send, tabId, msg.data);
@@ -383,4 +391,52 @@ export class WebSocketImproviseHandler implements HandlerContext {
     this.sessions.delete(sessionId);
   }
 
+  /**
+   * Handle a `shutdownInstance` control message from a web client.
+   *
+   * Authorization: only the orchestra owner may shut down. The relay tags
+   * shared (view-only) users with `_permission: 'view'`; absence means the
+   * requester is the owner whose CLI this is. View-only requests are
+   * rejected with a `forbidden` error rather than silently dropped so the
+   * UI can surface "you're not the owner" to non-owners.
+   *
+   * Idempotency: a shutdown already in progress is acked (broadcast +
+   * exit timer were already scheduled) but does not stack a second timer.
+   */
+  private handleShutdownInstance(ws: WSContext, permission: 'view' | undefined): void {
+    if (permission === 'view') {
+      console.log('[WebSocketImproviseHandler] Rejecting shutdownInstance from view-only user');
+      this.send(ws, {
+        type: 'error',
+        data: {
+          code: 'forbidden',
+          message: 'Only the owner can shut down this instance.'
+        }
+      });
+      return;
+    }
+
+    if (this.shutdownInProgress) {
+      console.log('[WebSocketImproviseHandler] shutdownInstance already in progress — ignoring duplicate request');
+      return;
+    }
+    this.shutdownInProgress = true;
+
+    // The CLI knows the request came from the owner (the relay only forwards
+    // owner traffic without a `_permission` tag), but does not receive the
+    // owner's userId on the wire. Logged as 'owner' for the audit trail.
+    console.log('[WebSocketImproviseHandler] shutdownInstance requested by owner — broadcasting shuttingDown and exiting');
+
+    this.broadcastToAll({ type: 'shuttingDown', data: { reason: 'user-requested' } });
+
+    // Mirrors the HTTP /api/shutdown route's 100ms delay so the broadcast
+    // has a chance to flush before process.exit tears down the socket.
+    setTimeout(() => {
+      if (this.instanceRegistry) {
+        this.instanceRegistry.unregister();
+      }
+      process.exit(0);
+    }, 100);
+  }
+
 }

package/server/services/websocket/index.ts

@@ -1,5 +1,4 @@
 // Copyright (c) 2025-present Mstro, Inc. All rights reserved.
-// Licensed under the MIT License. See LICENSE file for details.
 
 /**
  * WebSocket Improvise Module

package/server/services/websocket/msg-id-tracker.ts

@@ -1,5 +1,4 @@
 // Copyright (c) 2025-present Mstro, Inc. All rights reserved.
-// Licensed under the MIT License. See LICENSE file for details.
 
 /**
  * Idempotency tracker for client-sent message IDs.

package/server/services/websocket/plan-board-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 { existsSync, mkdirSync, readFileSync, unlinkSync, writeFileSync } from 'node:fs';
 import { join } from 'node:path';

package/server/services/websocket/plan-execution-handlers.ts

@@ -1,11 +1,11 @@
 // Copyright (c) 2025-present Mstro, Inc. All rights reserved.
-// Licensed under the MIT License. See LICENSE file for details.
 
 import { handlePlanPrompt } from '../plan/composer.js';
 import type { PlanExecutor } from '../plan/executor.js';
 import { parsePlanDirectory } from '../plan/parser.js';
 import type { HandlerContext } from './handler-context.js';
 import { denyIfViewOnly, executorCache, getExecutor } from './plan-helpers.js';
+import { mergePreUploadedAttachments } from './session-handlers.js';
 import type { WebSocketMessage, WSContext } from './types.js';
 
 // ============================================================================
@@ -25,7 +25,11 @@ export function handlePrompt(
     return;
   }
   const executionDir = boardId ? ctx.gitDirectories.get(boardId) : undefined;
-  handlePlanPrompt(ctx, ws, prompt, workingDir, boardId, executionDir).catch(error => {
+  // Pull in any chunked uploads stashed under this board's tabId by the
+  // composer paperclip / drag-drop path, so they flow into the plan prompt
+  // exactly like chat-tab attachments do.
+  const attachments = boardId ? mergePreUploadedAttachments(ctx, boardId, undefined) : undefined;
+  handlePlanPrompt(ctx, ws, prompt, workingDir, boardId, executionDir, attachments).catch(error => {
     ctx.send(ws, {
       type: 'planError',
       data: { error: error instanceof Error ? error.message : String(error) },

package/server/services/websocket/plan-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.
 
 /**
  * Plan Handlers — WebSocket message router for Plan view

package/server/services/websocket/plan-helpers.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 { mkdirSync, writeFileSync } from 'node:fs';
 import { join, resolve } from 'node:path';

package/server/services/websocket/plan-issue-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 { existsSync, mkdirSync, readFileSync, unlinkSync, writeFileSync } from 'node:fs';
 import { basename, join } from 'node:path';

package/server/services/websocket/plan-sprint-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 { existsSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs';
 import { join } from 'node:path';