mstro-app 0.4.52 → 0.5.1

package/server/services/sentry.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 } from 'node:fs'
 import { homedir } from 'node:os'

package/server/services/settings.ts

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

package/server/services/terminal/pty-manager.ts

@@ -1,5 +1,4 @@
 // Copyright (c) 2025-present Mstro, Inc. All rights reserved.
-// Licensed under the MIT License. See LICENSE file for details.
 
 /**
  * PTY Manager - Manages pseudo-terminal sessions for shell access.

package/server/services/terminal/pty-utils.ts

@@ -1,5 +1,4 @@
 // Copyright (c) 2025-present Mstro, Inc. All rights reserved.
-// Licensed under the MIT License. See LICENSE file for details.
 
 /**
  * PTY Utilities — node-pty loading, shell detection, scrollback buffer, and types.

package/server/services/websocket/autocomplete.ts

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

package/server/services/websocket/file-definition-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 { spawn } from 'node:child_process';
 import { join, relative } from 'node:path';

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

@@ -0,0 +1,190 @@
+// Copyright (c) 2025-present Mstro, Inc. All rights reserved.
+
+/**
+ * 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/file-explorer-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 {
   createDirectory,

package/server/services/websocket/file-search-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 { spawn } from 'node:child_process';
 import { relative } from 'node:path';

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

@@ -1,12 +1,13 @@
 // Copyright (c) 2025-present Mstro, Inc. All rights reserved.
-// Licensed under the MIT License. See LICENSE file for details.
 
 /**
  * Chunked File Upload Handler
  *
  * Receives files in chunks over WebSocket from remote web clients.
+ * The destination working directory is passed per-call (effective dir for the tab,
+ * which resolves to the worktree path when the tab is on a worktree).
  * - When `targetPath` is provided: streams to <workingDir>/<targetPath> (drag-drop into file tree).
- * - Otherwise: streams to .mstro/tmp/attachments/{tabId}/ (prompt attachments).
+ * - Otherwise: streams to <workingDir>/.mstro/tmp/attachments/{tabId}/ (prompt attachments).
  */
 
 import type { WriteStream } from 'node:fs';
@@ -50,7 +51,6 @@ export class FileUploadHandler {
   private cleanupInterval: ReturnType<typeof setInterval>;
 
   constructor(
-    private workingDir: string,
     private ctx?: HandlerContext,
   ) {
     // Periodically clean up stale uploads
@@ -74,6 +74,7 @@ export class FileUploadHandler {
     send: (ws: WSContext, response: WebSocketResponse) => void,
     tabId: string,
     data: { uploadId: string; fileName: string; fileSize: number; mimeType: string; isImage: boolean; totalChunks: number; targetPath?: string; overwrite?: boolean },
+    workingDir: string,
     permission?: 'view',
   ): void {
     const { uploadId, fileName, fileSize, mimeType, isImage, totalChunks, targetPath, overwrite } = data;
@@ -89,8 +90,8 @@ export class FileUploadHandler {
     }
 
     const resolved = targetPath !== undefined
-      ? resolveFileTreeTarget({ targetPath, fileName, workingDir: this.workingDir, permission, overwrite })
-      : resolveAttachmentTarget({ workingDir: this.workingDir, tabId, fileName });
+      ? resolveFileTreeTarget({ targetPath, fileName, workingDir, permission, overwrite })
+      : resolveAttachmentTarget({ workingDir, tabId, fileName });
 
     if (!resolved.ok) {
       sendError(resolved.error);

package/server/services/websocket/file-utils.ts

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

package/server/services/websocket/git-branch-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 { executeGitCommand, sendGitError } from './git-utils.js';
 import { findWorktreePathForBranch, handleTabWorktreeSwitch } from './git-worktree-handlers.js';

package/server/services/websocket/git-diff-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 { readFileSync } from 'node:fs';
 import { join } from 'node:path';

package/server/services/websocket/git-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 { resolve } from 'node:path';
 import { loadSkillPrompt } from '../plan/agent-loader.js';
@@ -8,7 +7,7 @@ import { handleGitCommitDiff, handleGitDiff, handleGitShowCommit } from './git-d
 import { handleGitDiscoverRepos, handleGitLog, handleGitSetDirectory } from './git-log-handlers.js';
 import { handleGitPRMessage } from './git-pr-handlers.js';
 import { handleGitCreateTag, handleGitListTags, handleGitPushTag } from './git-tag-handlers.js';
-import { executeGitCommand, parseGitStatus, sendGitError, spawnHaikuWithPrompt, stripCoauthorLines, truncateDiff } from './git-utils.js';
+import { classifyHaikuFailure, executeGitCommand, type HaikuResult, logCommitMessageEvent, parseGitStatus, sendGitError, spawnHaikuWithPrompt, stripCoauthorLines, truncateDiff } from './git-utils.js';
 import { handleGitWorktreeMessage } from './git-worktree-handlers.js';
 import type { HandlerContext } from './handler-context.js';
 import type { GitStatusResponse, WebSocketMessage, WSContext } from './types.js';
@@ -200,7 +199,50 @@ async function handleGitCommit(ctx: HandlerContext, ws: WSContext, msg: WebSocke
   }
 }
 
+/** Tabs currently generating an AI commit message. Prevents double-clicks
+ *  from spawning two `claude` subprocesses for the same tab and clobbering
+ *  the UI when the second response arrives. Module-scoped so it survives
+ *  HandlerContext lifecycle (one process per CLI machine). */
+const inflightCommitMessage = new Set<string>();
+
+const haikuSucceeded = (r: HaikuResult): boolean => r.exitCode === 0 && r.stdout.trim().length > 0;
+// rate_limit is terminal because a 500ms retry hits the same window the API
+// expects you to wait ~60s on; retrying just doubles user-perceived latency
+// before we surface the "wait a minute" message.
+const RETRY_TERMINAL_REASONS = new Set(['binary_missing', 'auth', 'rate_limit']);
+
+/** Run Haiku with one retry on transient failures. Logs each attempt. */
+async function runHaikuForCommitMessage(
+  prompt: string, systemPrompt: string, workingDir: string,
+  meta: { tabId: string; startedAt: number; diffBytes: number },
+): Promise<{ result: HaikuResult; attempts: number }> {
+  let result = await spawnHaikuWithPrompt(prompt, systemPrompt, workingDir);
+  if (haikuSucceeded(result)) return { result, attempts: 1 };
+
+  const first = classifyHaikuFailure(result);
+  if (RETRY_TERMINAL_REASONS.has(first.reason)) return { result, attempts: 1 };
+
+  logCommitMessageEvent(workingDir, {
+    tabId: meta.tabId, attempt: 1, success: false, reason: first.reason,
+    exitCode: result.exitCode, timedOut: result.timedOut,
+    stderrTail: (result.stderr || '').trim().slice(-500),
+    latencyMs: Date.now() - meta.startedAt, diffBytes: meta.diffBytes, willRetry: true,
+  });
+  await new Promise(r => setTimeout(r, 500));
+  result = await spawnHaikuWithPrompt(prompt, systemPrompt, workingDir);
+  return { result, attempts: 2 };
+}
+
 async function handleGitCommitWithAI(ctx: HandlerContext, ws: WSContext, msg: WebSocketMessage, tabId: string, workingDir: string): Promise<void> {
+  if (inflightCommitMessage.has(tabId)) {
+    // Drop the duplicate request silently — the user already has one in
+    // flight. Surfacing "already generating" as a toast is noisier than
+    // just ignoring the click.
+    return;
+  }
+  inflightCommitMessage.add(tabId);
+  const startedAt = Date.now();
+
   try {
     const statusResult = await executeGitCommand(['status', '--porcelain=v1'], workingDir);
     const { staged } = parseGitStatus(statusResult.stdout);
@@ -216,25 +258,37 @@ async function handleGitCommitWithAI(ctx: HandlerContext, ws: WSContext, msg: We
     const recentCommits = logResult.stdout.trim() || 'No recent commits';
     const stagedFiles = staged.map(f => `${f.status} ${f.path}`).join('\n');
     const diff = truncateDiff(diffResult.stdout);
+    const diffBytes = diffResult.stdout.length;
 
     const prompt = loadSkillPrompt('commit-message', { recentCommits, stagedFiles, diff }, workingDir)
       ?? `You are generating a git commit message for the following staged changes.\n\nRECENT COMMIT MESSAGES (for style reference):\n${recentCommits}\n\nSTAGED FILES:\n${stagedFiles}\n\nDIFF OF STAGED CHANGES:\n${diff}\n\nGenerate a commit message: imperative mood, max 72 characters, focus on "why". Respond with ONLY the commit message.`;
 
-    const result = await spawnHaikuWithPrompt(
-      prompt,
-      'You are a commit message assistant. Respond with only the commit message, no preamble or explanation.',
-      workingDir,
-    );
+    const systemPrompt = 'You are a commit message assistant. Respond with only the commit message, no preamble or explanation.';
+
+    const { result, attempts } = await runHaikuForCommitMessage(prompt, systemPrompt, workingDir, { tabId, startedAt, diffBytes });
 
-    if (result.exitCode !== 0 || !result.stdout.trim()) {
-      console.error('[WebSocketImproviseHandler] Claude commit message error:', result.stderr || 'No output');
-      ctx.send(ws, { type: 'gitError', tabId, data: { error: 'Failed to generate commit message' } });
+    if (!haikuSucceeded(result)) {
+      const failure = classifyHaikuFailure(result);
+      logCommitMessageEvent(workingDir, {
+        tabId, attempt: attempts, success: false, reason: failure.reason,
+        exitCode: result.exitCode, timedOut: result.timedOut,
+        stderrTail: (result.stderr || '').trim().slice(-500),
+        latencyMs: Date.now() - startedAt, diffBytes,
+      });
+      console.error(`[git] commit-message failed (${failure.reason}):`, result.stderr || 'no stderr');
+      ctx.send(ws, { type: 'gitError', tabId, data: { error: failure.userMessage } });
       return;
     }
 
     const commitMessage = extractCommitMessage(result.stdout.trim());
     const autoCommit = !!msg.data?.autoCommit;
 
+    logCommitMessageEvent(workingDir, {
+      tabId, attempt: attempts, success: true,
+      latencyMs: Date.now() - startedAt, diffBytes, autoCommit,
+      messageLength: commitMessage.length,
+    });
+
     ctx.send(ws, { type: 'gitCommitMessage', tabId, data: { message: commitMessage, autoCommit } });
 
     if (autoCommit) {
@@ -250,6 +304,8 @@ async function handleGitCommitWithAI(ctx: HandlerContext, ws: WSContext, msg: We
     }
   } catch (error: unknown) {
     sendGitError(ctx, ws, tabId, error);
+  } finally {
+    inflightCommitMessage.delete(tabId);
   }
 }
 

package/server/services/websocket/git-head-watcher.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, type FSWatcher, watch } from 'node:fs';
 import { join } from 'node:path';

package/server/services/websocket/git-log-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, readdirSync } from 'node:fs';
 import { join, resolve } from 'node:path';

package/server/services/websocket/git-pr-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 { loadSkillPrompt } from '../plan/agent-loader.js';
 import { getPrBaseBranch, setPrBaseBranch } from '../settings.js';

package/server/services/websocket/git-tag-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 { executeGitCommand, sendGitError } from './git-utils.js';
 import type { HandlerContext } from './handler-context.js';

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

@@ -1,8 +1,8 @@
 // Copyright (c) 2025-present Mstro, Inc. All rights reserved.
-// Licensed under the MIT License. See LICENSE file for details.
 
 import { spawn } from 'node:child_process';
-import { existsSync, mkdirSync, unlinkSync, writeFileSync } from 'node:fs';
+import { randomUUID } from 'node:crypto';
+import { appendFileSync, existsSync, mkdirSync, unlinkSync, writeFileSync } from 'node:fs';
 import { join } from 'node:path';
 import type { HandlerContext } from './handler-context.js';
 import type { GitFileStatus, WSContext } from './types.js';
@@ -171,17 +171,31 @@ export function truncateDiff(diff: string, maxLength = 8000): string {
   return `${diff.slice(0, headSize)}\n\n... [diff truncated] ...\n\n${diff.slice(-tailSize)}`;
 }
 
-/** Spawn Claude Haiku with a prompt file and return captured output. */
+/** Result of a Haiku spawn. `timedOut` is set when the process was killed by our timer. */
+export interface HaikuResult {
+  stdout: string;
+  stderr: string;
+  exitCode: number;
+  timedOut: boolean;
+}
+
+/** Spawn Claude Haiku with a prompt file and return captured output.
+ *
+ * Default timeout is 90s — measured p99 of Haiku responses is ~31s for tiny
+ * bouncer prompts; commit-message and PR-description prompts ship a full diff
+ * and run materially longer. 90s gives a 3x margin while still failing fast
+ * enough that the UI doesn't spin forever. */
 export function spawnHaikuWithPrompt(
   prompt: string,
   systemPrompt: string,
   workingDir: string,
-  timeoutMs = 30000,
-): Promise<{ stdout: string; stderr: string; exitCode: number }> {
+  timeoutMs = 90000,
+): Promise<HaikuResult> {
   return new Promise((resolve) => {
     const tempDir = join(workingDir, '.mstro', 'tmp');
     if (!existsSync(tempDir)) mkdirSync(tempDir, { recursive: true });
-    const promptFile = join(tempDir, `haiku-${Date.now()}.txt`);
+    // randomUUID — Date.now() collided when two requests fired in the same ms.
+    const promptFile = join(tempDir, `haiku-${randomUUID()}.txt`);
     writeFileSync(promptFile, prompt);
 
     const args = ['--print', '--model', 'haiku', '--system-prompt', systemPrompt, promptFile];
@@ -189,25 +203,71 @@ export function spawnHaikuWithPrompt(
 
     let stdout = '';
     let stderr = '';
+    let timedOut = false;
     proc.stdout?.on('data', (d: Buffer) => { stdout += d.toString(); });
     proc.stderr?.on('data', (d: Buffer) => { stderr += d.toString(); });
 
-    const timer = setTimeout(() => proc.kill(), timeoutMs);
+    const timer = setTimeout(() => { timedOut = true; proc.kill(); }, timeoutMs);
 
     proc.on('close', (code) => {
       clearTimeout(timer);
       try { unlinkSync(promptFile); } catch { /* ignore cleanup errors */ }
-      resolve({ stdout, stderr, exitCode: code ?? 1 });
+      resolve({ stdout, stderr, exitCode: code ?? 1, timedOut });
     });
 
     proc.on('error', (err: Error) => {
       clearTimeout(timer);
       try { unlinkSync(promptFile); } catch { /* ignore cleanup errors */ }
-      resolve({ stdout: '', stderr: err.message, exitCode: 1 });
+      // ENOENT here means the `claude` binary wasn't found on PATH.
+      const enoent = (err as NodeJS.ErrnoException).code === 'ENOENT';
+      resolve({ stdout: '', stderr: enoent ? `claude: command not found (${err.message})` : err.message, exitCode: 1, timedOut: false });
     });
   });
 }
 
+/** Map a Haiku failure to an actionable user-facing message + a stable reason code. */
+export function classifyHaikuFailure(result: HaikuResult): { reason: string; userMessage: string } {
+  const stderr = (result.stderr || '').toLowerCase();
+  const stdout = (result.stdout || '').toLowerCase();
+  const combined = `${stderr} ${stdout}`;
+
+  if (result.timedOut) {
+    return { reason: 'timeout', userMessage: 'Claude took too long to respond. Try again, or stage fewer files at once.' };
+  }
+  if (combined.includes('command not found') || combined.includes('enoent')) {
+    return { reason: 'binary_missing', userMessage: 'Claude CLI is not installed or not on PATH. Install it with `npm i -g @anthropic-ai/claude-code` and re-launch mstro.' };
+  }
+  if (/not\s+(logged|signed)\s*in|not\s+authenticated|please\s+(log|sign)\s*in|api\s*key|unauthor/.test(combined)) {
+    return { reason: 'auth', userMessage: 'Claude CLI is not authenticated. Run `claude /login` in a terminal, then try again.' };
+  }
+  if (/rate\s*limit|usage\s*limit|429|too\s+many\s+requests/.test(combined)) {
+    return { reason: 'rate_limit', userMessage: 'Claude rate limit reached. Wait a minute and try again.' };
+  }
+  if (/overloaded|529|service\s+unavailable|503/.test(combined)) {
+    return { reason: 'overloaded', userMessage: "Claude is temporarily overloaded. Try again in a few seconds." };
+  }
+  if (result.exitCode === 0 && !result.stdout.trim()) {
+    return { reason: 'empty_output', userMessage: 'Claude returned an empty response. Try again.' };
+  }
+
+  const tail = (result.stderr || result.stdout || '').trim().slice(-200);
+  return { reason: 'unknown', userMessage: `Failed to generate commit message${tail ? `: ${tail}` : ''}` };
+}
+
+/** Append a structured event to .mstro/logs/commit-message.jsonl for observability. */
+export function logCommitMessageEvent(workingDir: string, entry: Record<string, unknown>): void {
+  try {
+    const logDir = join(workingDir, '.mstro', 'logs');
+    if (!existsSync(logDir)) mkdirSync(logDir, { recursive: true });
+    const logFile = join(logDir, 'commit-message.jsonl');
+    const line = `${JSON.stringify({ timestamp: new Date().toISOString(), ...entry })}\n`;
+    appendFileSync(logFile, line, 'utf-8');
+  } catch (err) {
+    // Logging must never break the user-facing flow.
+    console.error('[git] failed to write commit-message log:', err);
+  }
+}
+
 /**
  * Strip injected coauthor/attribution lines from a commit message.
  */