mstro-app 0.4.35 → 0.4.38

package/server/cli/headless/claude-invoker-stream.ts

@@ -6,8 +6,73 @@ import type { NativeTimeoutDetector } from './native-timeout-detector.js';
 import { classifyError } from './stall-assessor.js';
 import type { ResolvedHeadlessConfig, ToolUseAccumulator } from './types.js';
 
-// biome-ignore lint/suspicious/noExplicitAny: external CLI stream JSON with heterogeneous shapes
-type StreamJson = any;
+interface StreamContentBlock {
+  type: string;
+  text?: string;
+  thinking?: string;
+  name?: string;
+  id?: string;
+  input?: Record<string, unknown>;
+  tool_use_id?: string;
+  content?: string | unknown;
+  is_error?: boolean;
+}
+
+interface StreamTokenUsage {
+  input_tokens?: number;
+  output_tokens?: number;
+  cache_creation_input_tokens?: number;
+  cache_read_input_tokens?: number;
+}
+
+type StreamJson = {
+  type: string;
+  subtype?: string;
+  session_id?: string;
+  stop_reason?: string;
+  is_error?: boolean;
+  error?: string | { message?: string };
+  result?: string;
+  message?: {
+    content?: StreamContentBlock[];
+    usage?: StreamTokenUsage;
+  };
+  event?: {
+    type: string;
+    delta?: {
+      type: string;
+      thinking?: string;
+      text?: string;
+      partial_json?: string;
+    };
+    content_block?: {
+      type: string;
+      name?: string;
+      id?: string;
+    };
+    index?: number;
+    message?: { usage?: StreamTokenUsage };
+    usage?: { output_tokens?: number };
+  };
+  usage?: StreamTokenUsage;
+  delta?: {
+    type: string;
+    thinking?: string;
+    text?: string;
+    partial_json?: string;
+  };
+  content_block?: {
+    type: string;
+    name?: string;
+    id?: string;
+  };
+  index?: number;
+  text?: string;
+  thinking?: string;
+  name?: string;
+  id?: string;
+  input?: Record<string, unknown>;
+};
 
 export interface StreamHandlerContext {
   config: ResolvedHeadlessConfig;
@@ -29,6 +94,11 @@ export interface StreamHandlerContext {
   lastTokenActivityTime: number;
   /** Claude Code result event stop_reason (e.g., 'end_turn', 'max_tokens') */
   stopReason?: string;
+  /** True once any stream_event text_delta has been received — used to skip
+   *  duplicate text from assistant messages emitted alongside streaming deltas. */
+  hasReceivedTextDeltas: boolean;
+  /** Same guard for thinking deltas */
+  hasReceivedThinkingDeltas: boolean;
 }
 
 /** Log messages when verbose mode is enabled */
@@ -61,6 +131,8 @@ function handleThinkingDelta(event: StreamJson, ctx: StreamHandlerContext): stri
     return ctx.accumulatedThinking;
   }
 
+  ctx.hasReceivedThinkingDeltas = true;
+
   if (ctx.resumeAssessmentActive) {
     ctx.resumeAssessmentActive = false;
     if (ctx.resumeAssessmentBuffer) {
@@ -92,6 +164,7 @@ function handleTextDelta(event: StreamJson, ctx: StreamHandlerContext): string {
     return ctx.accumulatedAssistantResponse;
   }
 
+  ctx.hasReceivedTextDeltas = true;
   const text = event.delta.text;
   const updated = ctx.accumulatedAssistantResponse + text;
 
@@ -211,30 +284,32 @@ function handleToolResult(parsed: StreamJson, ctx: StreamHandlerContext): void {
 // ========== Stream Processing ==========
 
 function handleAssistantTextBlock(block: StreamJson, ctx: StreamHandlerContext): void {
-  ctx.accumulatedAssistantResponse += block.text;
-  ctx.config.outputCallback?.(block.text);
+  if (ctx.hasReceivedTextDeltas) return;
+  ctx.accumulatedAssistantResponse += block.text!;
+  ctx.config.outputCallback?.(block.text!);
 }
 
 function handleAssistantThinkingBlock(block: StreamJson, ctx: StreamHandlerContext): void {
-  ctx.accumulatedThinking += block.thinking;
+  if (ctx.hasReceivedThinkingDeltas) return;
+  ctx.accumulatedThinking += block.thinking!;
   if (ctx.config.thinkingCallback) {
-    ctx.config.thinkingCallback(block.thinking);
+    ctx.config.thinkingCallback(block.thinking!);
   } else {
-    ctx.config.outputCallback?.(block.thinking);
+    ctx.config.outputCallback?.(block.thinking!);
   }
 }
 
 function handleAssistantToolUseBlock(block: StreamJson, ctx: StreamHandlerContext): void {
   const toolInput = block.input || {};
   ctx.accumulatedToolUse.push({
-    toolName: block.name, toolId: block.id,
+    toolName: block.name!, toolId: block.id!,
     toolInput, startTime: Date.now(),
   });
   ctx.config.toolUseCallback?.({
-    type: 'tool_start', toolName: block.name, toolId: block.id, index: 0,
+    type: 'tool_start', toolName: block.name!, toolId: block.id!, index: 0,
   });
   ctx.config.toolUseCallback?.({
-    type: 'tool_complete', toolName: block.name, toolId: block.id,
+    type: 'tool_complete', toolName: block.name!, toolId: block.id!,
     index: 0, completeInput: toolInput,
   });
 }
@@ -266,29 +341,36 @@ function handleAssistantMessage(parsed: StreamJson, ctx: StreamHandlerContext):
   }
 }
 
+function extractErrorMessage(parsed: StreamJson): string {
+  const errObj = typeof parsed.error === 'object' ? parsed.error?.message : parsed.error;
+  return errObj || String(parsed.message ?? '') || JSON.stringify(parsed);
+}
+
+function handleResultEvent(parsed: StreamJson, ctx: StreamHandlerContext): boolean {
+  handleResultTokenUsage(parsed, ctx);
+  if (parsed.stop_reason) {
+    ctx.stopReason = parsed.stop_reason;
+  }
+  if (parsed.is_error) {
+    const errorMessage = parsed.error || parsed.result || 'Unknown error in result';
+    ctx.config.outputCallback?.(`\n[[MSTRO_ERROR:CLAUDE_RESULT_ERROR]] ${errorMessage}\n`);
+    return true;
+  }
+  if (!ctx.accumulatedAssistantResponse && parsed.result && typeof parsed.result === 'string') {
+    ctx.accumulatedAssistantResponse = parsed.result;
+    ctx.config.outputCallback?.(parsed.result);
+  }
+  return false;
+}
+
 export function processStreamEvent(parsed: StreamJson, ctx: StreamHandlerContext): void {
   if (parsed.type === 'error') {
-    const errorMessage = parsed.error?.message || parsed.message || JSON.stringify(parsed);
-    ctx.config.outputCallback?.(`\n[[MSTRO_ERROR:CLAUDE_ERROR]] ${errorMessage}\n`);
+    ctx.config.outputCallback?.(`\n[[MSTRO_ERROR:CLAUDE_ERROR]] ${extractErrorMessage(parsed)}\n`);
     return;
   }
 
   if (parsed.type === 'result') {
-    handleResultTokenUsage(parsed, ctx);
-    if (parsed.stop_reason) {
-      ctx.stopReason = parsed.stop_reason;
-    }
-    if (parsed.is_error) {
-      const errorMessage = parsed.error || parsed.result || 'Unknown error in result';
-      ctx.config.outputCallback?.(`\n[[MSTRO_ERROR:CLAUDE_RESULT_ERROR]] ${errorMessage}\n`);
-      return;
-    }
-    // Fallback: capture the result text if streaming deltas didn't accumulate anything.
-    // This happens when Claude Code runs skill commands or other non-streaming code paths.
-    if (!ctx.accumulatedAssistantResponse && parsed.result && typeof parsed.result === 'string') {
-      ctx.accumulatedAssistantResponse = parsed.result;
-      ctx.config.outputCallback?.(parsed.result);
-    }
+    if (handleResultEvent(parsed, ctx)) return;
   }
 
   if (parsed.type === 'stream_event' && parsed.event) {
@@ -314,9 +396,9 @@ function handleToolStart(event: StreamJson, ctx: StreamHandlerContext): void {
     }
   }
 
-  const toolName = event.content_block.name;
-  const toolId = event.content_block.id;
-  const index = event.index;
+  const toolName = event.content_block.name!;
+  const toolId = event.content_block.id!;
+  const index = event.index!;
 
   ctx.toolInputBuffers.set(index, { name: toolName, id: toolId, inputJson: '', startTime: Date.now() });
   ctx.config.toolUseCallback?.({ type: 'tool_start', toolName, toolId, index });
@@ -326,7 +408,7 @@ function handleToolStart(event: StreamJson, ctx: StreamHandlerContext): void {
 function handleToolInputDelta(event: StreamJson, ctx: StreamHandlerContext): void {
   if (event.type !== 'content_block_delta' || event.delta?.type !== 'input_json_delta') return;
 
-  const index = event.index;
+  const index = event.index!;
   const partialJson = event.delta.partial_json;
   const toolBuffer = ctx.toolInputBuffers.get(index);
   if (toolBuffer) toolBuffer.inputJson += partialJson;
@@ -337,7 +419,7 @@ function handleToolInputDelta(event: StreamJson, ctx: StreamHandlerContext): voi
 function handleToolComplete(event: StreamJson, ctx: StreamHandlerContext): void {
   if (event.type !== 'content_block_stop') return;
 
-  const index = event.index;
+  const index = event.index!;
   const toolBuffer = ctx.toolInputBuffers.get(index);
   if (!toolBuffer) return;
 

package/server/cli/headless/claude-invoker.ts

@@ -63,6 +63,8 @@ export async function executeClaudeCommand(
     apiTokenUsage: { inputTokens: 0, outputTokens: 0 },
     currentStepOutputTokens: 0,
     lastTokenActivityTime: Date.now(),
+    hasReceivedTextDeltas: false,
+    hasReceivedThinkingDeltas: false,
   };
 
   const stallState: StallState = {

package/server/cli/improvisation-session-manager.ts

@@ -131,9 +131,10 @@ export class ImprovisationSessionManager extends EventEmitter {
 
   // ========== Main Execution ==========
 
-  async executePrompt(userPrompt: string, attachments?: FileAttachment[], options?: { workingDir?: string; isAutoContinue?: boolean }): Promise<MovementRecord> {
+  async executePrompt(userPrompt: string, attachments?: FileAttachment[], options?: { workingDir?: string; isAutoContinue?: boolean; displayPrompt?: string }): Promise<MovementRecord> {
     const _execStart = Date.now();
     const isAutoContinue = options?.isAutoContinue ?? false;
+    const displayPrompt = options?.displayPrompt ?? userPrompt;
     this._isExecuting = true;
     this._cancelled = false;
     this._cancelCompleteEmitted = false;
@@ -145,9 +146,9 @@ export class ImprovisationSessionManager extends EventEmitter {
     this.executionEventLog = [];
 
     const sequenceNumber = this.history.movements.length + 1;
-    this._currentUserPrompt = userPrompt;
+    this._currentUserPrompt = displayPrompt;
     this._currentSequenceNumber = sequenceNumber;
-    this.emit('onMovementStart', sequenceNumber, userPrompt, isAutoContinue);
+    this.emit('onMovementStart', sequenceNumber, displayPrompt, isAutoContinue);
     trackEvent(AnalyticsEvents.IMPROVISE_PROMPT_RECEIVED, {
       prompt_length: userPrompt.length,
       has_attachments: !!(attachments && attachments.length > 0),
@@ -162,7 +163,7 @@ export class ImprovisationSessionManager extends EventEmitter {
     const pendingMovement: MovementRecord = {
       id: `prompt-${sequenceNumber}`,
       sequenceNumber,
-      userPrompt,
+      userPrompt: displayPrompt,
       timestamp: new Date().toISOString(),
       tokensUsed: 0,
       summary: '',
@@ -176,7 +177,7 @@ export class ImprovisationSessionManager extends EventEmitter {
     try {
       this.executionEventLog.push({
         type: 'movementStart',
-        data: { sequenceNumber, prompt: userPrompt, timestamp: Date.now(), executionStartTimestamp: this._executionStartTimestamp },
+        data: { sequenceNumber, prompt: displayPrompt, timestamp: Date.now(), executionStartTimestamp: this._executionStartTimestamp },
         timestamp: Date.now(),
       });
 
@@ -201,7 +202,7 @@ export class ImprovisationSessionManager extends EventEmitter {
       let result = await this.runRetryLoop(state, sequenceNumber, promptWithAttachments, imageAttachments, options?.workingDir);
 
       if (this._cancelled) {
-        return this.handleCancelledExecution(result, userPrompt, sequenceNumber, _execStart);
+        return this.handleCancelledExecution(result, displayPrompt, sequenceNumber, _execStart);
       }
 
       if (state.contextLost) this.claudeSessionId = undefined;
@@ -209,7 +210,7 @@ export class ImprovisationSessionManager extends EventEmitter {
       this.captureSessionAndSurfaceErrors(result);
       this.isFirstPrompt = false;
 
-      const movement = this.buildMovementRecord(result, userPrompt, sequenceNumber, _execStart, state.retryLog, isAutoContinue);
+      const movement = this.buildMovementRecord(result, displayPrompt, sequenceNumber, _execStart, state.retryLog, isAutoContinue);
       this.handleConflicts(result);
       this.persistMovement(movement);
 
@@ -218,44 +219,12 @@ export class ImprovisationSessionManager extends EventEmitter {
       this.executionEventLog = [];
 
       this.emitMovementComplete(movement, result, _execStart, sequenceNumber);
-
-      if (this.shouldAutoContinue(result, userPrompt)) {
-        this.scheduleAutoContinue();
-      }
+      this.maybeAutoContinue(result, userPrompt);
 
       return movement;
 
     } catch (error: unknown) {
-      this._isExecuting = false;
-      this._executionStartTimestamp = undefined;
-      this.executionEventLog = [];
-      this.currentRunner = null;
-
-      // Update the pending movement with error info so it's not lost
-      const errorMessage = error instanceof Error ? error.message : String(error);
-      const errorMovement: MovementRecord = {
-        id: `prompt-${sequenceNumber}`,
-        sequenceNumber,
-        userPrompt,
-        timestamp: new Date().toISOString(),
-        tokensUsed: 0,
-        summary: '',
-        filesModified: [],
-        errorOutput: errorMessage,
-        durationMs: Date.now() - _execStart,
-      };
-      this.persistMovement(errorMovement);
-
-      this.emit('onMovementError', error);
-      trackEvent(AnalyticsEvents.IMPROVISE_MOVEMENT_ERROR, {
-        error_message: errorMessage.slice(0, 200),
-        sequence_number: sequenceNumber,
-        duration_ms: Date.now() - _execStart,
-        model: this.options.model || 'default',
-      });
-      this.queueOutput(`\n❌ Error: ${errorMessage}\n`);
-      this.flushOutputQueue();
-      throw error;
+      this.handleExecutionError(error, displayPrompt, sequenceNumber, _execStart);
     } finally {
       this.flushOutputQueue();
     }
@@ -410,6 +379,43 @@ export class ImprovisationSessionManager extends EventEmitter {
     return cancelledMovement;
   }
 
+  private handleExecutionError(
+    error: unknown,
+    displayPrompt: string,
+    sequenceNumber: number,
+    execStart: number,
+  ): never {
+    this._isExecuting = false;
+    this._executionStartTimestamp = undefined;
+    this.executionEventLog = [];
+    this.currentRunner = null;
+
+    const errorMessage = error instanceof Error ? error.message : String(error);
+    const errorMovement: MovementRecord = {
+      id: `prompt-${sequenceNumber}`,
+      sequenceNumber,
+      userPrompt: displayPrompt,
+      timestamp: new Date().toISOString(),
+      tokensUsed: 0,
+      summary: '',
+      filesModified: [],
+      errorOutput: errorMessage,
+      durationMs: Date.now() - execStart,
+    };
+    this.persistMovement(errorMovement);
+
+    this.emit('onMovementError', error);
+    trackEvent(AnalyticsEvents.IMPROVISE_MOVEMENT_ERROR, {
+      error_message: errorMessage.slice(0, 200),
+      sequence_number: sequenceNumber,
+      duration_ms: Date.now() - execStart,
+      model: this.options.model || 'default',
+    });
+    this.queueOutput(`\n❌ Error: ${errorMessage}\n`);
+    this.flushOutputQueue();
+    throw error;
+  }
+
   // ========== Post-Execution Helpers ==========
 
   private captureSessionAndSurfaceErrors(result: HeadlessRunResult): void {
@@ -493,6 +499,15 @@ export class ImprovisationSessionManager extends EventEmitter {
   private _autoContinuePending = false;
   private static readonly MAX_AUTO_CONTINUES = 1;
 
+  private maybeAutoContinue(result: HeadlessRunResult, userPrompt: string): void {
+    const isStallKill = !this._cancelled && !!result.signalName;
+    if (isStallKill && this._autoContinueCount < ImprovisationSessionManager.MAX_AUTO_CONTINUES) {
+      this.scheduleAutoContinue('Process stalled');
+    } else if (this.shouldAutoContinue(result, userPrompt)) {
+      this.scheduleAutoContinue();
+    }
+  }
+
   private shouldAutoContinue(result: HeadlessRunResult, _userPrompt: string): boolean {
     if (this._autoContinueCount >= ImprovisationSessionManager.MAX_AUTO_CONTINUES) return false;
     if (this._cancelled) return false;
@@ -510,10 +525,11 @@ export class ImprovisationSessionManager extends EventEmitter {
     return thinkingLen >= responseLen * 3;
   }
 
-  private scheduleAutoContinue(): void {
+  private scheduleAutoContinue(reason?: string): void {
     this._autoContinueCount++;
     this._autoContinuePending = true;
-    this.queueOutput('\n⟳ Response appears incomplete — auto-continuing…\n');
+    const msg = reason || 'Response appears incomplete';
+    this.queueOutput(`\n[[MSTRO_AUTO_CONTINUE]] ${msg} — resuming session (retry ${this._autoContinueCount}/${ImprovisationSessionManager.MAX_AUTO_CONTINUES}).\n`);
     this.flushOutputQueue();
 
     setImmediate(() => {

package/server/services/plan/executor.ts

@@ -129,6 +129,8 @@ export class PlanExecutor extends EventEmitter {
     this.pmDir = resolvePmDir(this.workingDir);
     this.boardDir = this.resolveBoardDir();
 
+    this.recoverStaleIssues();
+
     const stallResult = await this.runWaveLoop();
 
     this.metrics.totalDuration = Date.now() - startTime;
@@ -409,6 +411,45 @@ export class PlanExecutor extends EventEmitter {
     return 0;
   }
 
+  // ── Recovery ─────────────────────────────────────────────────
+
+  /**
+   * Recover from a previous interrupted execution by reverting stale
+   * `in_progress` and `in_review` issues back to `todo`. Without this,
+   * these issues block the dependency graph and cause the executor to
+   * find zero ready issues, making "Implement" appear to do nothing.
+   */
+  private recoverStaleIssues(): void {
+    const pmDir = this.pmDir;
+    if (!pmDir) return;
+
+    const effectiveBoardId = this.boardId ?? this.resolveActiveBoardId();
+    const issues = effectiveBoardId
+      ? this.loadBoardIssues(pmDir, effectiveBoardId)
+      : this.loadProjectIssues();
+
+    if (!issues) return;
+
+    const staleStatuses = new Set(['in_progress', 'in_review']);
+    const recovered: string[] = [];
+
+    for (const issue of issues) {
+      if (issue.type === 'epic') continue;
+      if (staleStatuses.has(issue.status)) {
+        this.updateIssueFrontMatter(issue.path, 'todo');
+        recovered.push(`${issue.id} (${issue.status} → todo)`);
+      }
+    }
+
+    if (recovered.length > 0) {
+      this.emit('output', {
+        issueId: 'recovery',
+        text: `Recovered ${recovered.length} issue${recovered.length > 1 ? 's' : ''} from previous interrupted execution: ${recovered.join(', ')}`,
+      });
+      this.emit('stateUpdated');
+    }
+  }
+
   // ── Helpers ──────────────────────────────────────────────────
 
   /** Read the board's maxParallelAgents setting, falling back to default. */
@@ -470,7 +511,7 @@ export class PlanExecutor extends EventEmitter {
 
     const readyIssues = resolveReadyToWork(issues, this.epicScope ?? undefined);
     if (readyIssues.length === 0) {
-      this.emit('complete', this.epicScope ? 'All epic issues are done or blocked' : 'All work is done or blocked');
+      this.emit('complete', this.buildCompletionReason(issues));
       if (effectiveBoardId) {
         this.tryCompleteBoardIfDone(pmDir, effectiveBoardId, issues);
       }
@@ -551,6 +592,15 @@ export class PlanExecutor extends EventEmitter {
     }
   }
 
+  private buildCompletionReason(issues: Issue[]): string {
+    const nonEpic = issues.filter(i => i.type !== 'epic');
+    const done = nonEpic.filter(i => i.status === 'done' || i.status === 'cancelled').length;
+    const blocked = nonEpic.filter(i => i.status === 'todo').length;
+    if (done === nonEpic.length) return this.epicScope ? 'All epic issues are done' : 'All issues are done';
+    if (blocked > 0) return `${done}/${nonEpic.length} issues done, ${blocked} blocked by incomplete dependencies`;
+    return this.epicScope ? 'All epic issues are done or blocked' : 'All work is done or blocked';
+  }
+
   private revertIncompleteIssues(issues: Issue[]): void {
     const pmDir = this.pmDir;
     if (!pmDir) return;

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

@@ -391,6 +391,30 @@ async function detectMergeConflicts(mainPath: string): Promise<string[]> {
   return result.stdout.trim().split('\n').filter(f => f.trim());
 }
 
+async function removeWorktreeWithFallback(
+  mainPath: string,
+  worktreePath: string,
+): Promise<{ success: boolean; warning?: string }> {
+  const removeResult = await executeGitCommand(['worktree', 'remove', worktreePath], mainPath);
+  if (removeResult.exitCode === 0) return { success: true };
+  const forceResult = await executeGitCommand(['worktree', 'remove', '--force', worktreePath], mainPath);
+  if (forceResult.exitCode === 0) return { success: true };
+  return { success: false, warning: `Failed to remove worktree: ${forceResult.stderr || 'unknown error'}` };
+}
+
+async function deleteBranchAfterMerge(
+  mainPath: string,
+  branchName: string,
+  strategy: string,
+): Promise<string | undefined> {
+  const deleteFlag = strategy === 'squash' ? '-D' : '-d';
+  const result = await executeGitCommand(['branch', deleteFlag, branchName], mainPath);
+  if (result.exitCode !== 0) {
+    return `Failed to delete branch: ${result.stderr || 'unknown error'}`;
+  }
+  return undefined;
+}
+
 async function cleanupAfterMerge(
   mainPath: string,
   sourceBranch: string,
@@ -405,25 +429,17 @@ async function cleanupAfterMerge(
     const wtList = await executeGitCommand(['worktree', 'list', '--porcelain'], mainPath);
     const worktreePath = findWorktreePathForBranch(wtList.stdout, sourceBranch);
     if (worktreePath && worktreePath !== mainPath) {
-      const removeResult = await executeGitCommand(['worktree', 'remove', worktreePath], mainPath);
-      if (removeResult.exitCode !== 0) {
-        const forceResult = await executeGitCommand(['worktree', 'remove', '--force', worktreePath], mainPath);
-        if (forceResult.exitCode !== 0) {
-          warnings.push(`Failed to remove worktree: ${forceResult.stderr || 'unknown error'}`);
-        } else {
-          removedWorktreePath = worktreePath;
-        }
-      } else {
+      const result = await removeWorktreeWithFallback(mainPath, worktreePath);
+      if (result.success) {
         removedWorktreePath = worktreePath;
+      } else if (result.warning) {
+        warnings.push(result.warning);
       }
     }
   }
   if (deleteBranch) {
-    const deleteFlag = strategy === 'squash' ? '-D' : '-d';
-    const branchResult = await executeGitCommand(['branch', deleteFlag, sourceBranch], mainPath);
-    if (branchResult.exitCode !== 0) {
-      warnings.push(`Failed to delete branch: ${branchResult.stderr || 'unknown error'}`);
-    }
+    const warning = await deleteBranchAfterMerge(mainPath, sourceBranch, strategy);
+    if (warning) warnings.push(warning);
   }
   await executeGitCommand(['worktree', 'prune'], mainPath);
   return { warnings, removedWorktreePath };

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

@@ -5,6 +5,7 @@ import type { FileAttachment, ImprovisationSessionManager } from '../../cli/impr
 import { getModel } from '../settings.js';
 import type { HandlerContext } from './handler-context.js';
 import { runQualityScan } from './quality-service.js';
+import { resolveSkillPrompt } from './skill-handlers.js';
 import type { WebSocketMessage, WSContext } from './types.js';
 
 // Re-export from extracted modules for backward compatibility
@@ -191,7 +192,22 @@ export function handleSessionMessage(ctx: HandlerContext, ws: WSContext, msg: We
       const session = requireSession(ctx, ws, tabId);
       const worktreeDir = ctx.gitDirectories.get(tabId);
       const attachments = mergePreUploadedAttachments(ctx, tabId, msg.data.attachments);
-      session.executePrompt(msg.data.prompt, attachments, { workingDir: worktreeDir });
+
+      // Resolve slash commands (e.g. "/code-review") to their SKILL.md prompt content.
+      // Claude Code's -p headless mode doesn't support skills natively, so we load
+      // the skill's instructions and pass them as the actual prompt.
+      const rawPrompt = msg.data.prompt as string;
+      const effectiveDir = worktreeDir || session.getSessionInfo().workingDir;
+      const resolved = resolveSkillPrompt(rawPrompt, effectiveDir);
+
+      session.executePrompt(
+        resolved ? resolved.prompt : rawPrompt,
+        attachments,
+        {
+          workingDir: worktreeDir,
+          displayPrompt: resolved ? rawPrompt : undefined,
+        },
+      );
       break;
     }
     case 'cancel': {