mstro-app 0.4.28 → 0.4.32

package/server/services/plan/agent-loader.ts

@@ -2,11 +2,12 @@
 // Licensed under the MIT License. See LICENSE file for details.
 
 /**
- * Agent Prompt Loader — loads review agent prompts from markdown files.
+ * Agent Prompt Loader — loads review agent prompts from Skills and markdown files.
  *
  * Resolution order (first match wins):
  *   1. Board-level override:  {boardDir}/agents/{agentName}.md
- *   2. System default:        cli/server/services/plan/agents/{agentName}.md
+ *   2. Project Skill:         {workingDir}/.claude/skills/{agentName}/SKILL.md
+ *   3. System default:        cli/server/services/plan/agents/{agentName}.md
  *
  * Files use YAML frontmatter + markdown body with {{variable}} placeholders.
  * Falls back to null when no file is found (caller should use hardcoded fallback).
@@ -34,40 +35,112 @@ function interpolate(template: string, variables: Record<string, string>): strin
   });
 }
 
+/** Try to load and interpolate a prompt file. Returns null on failure. */
+function tryLoadFile(filePath: string, variables: Record<string, string>): string | null {
+  if (!existsSync(filePath)) return null;
+  try {
+    const raw = readFileSync(filePath, 'utf-8');
+    return interpolate(stripFrontmatter(raw), variables);
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Resolve the project root by walking up from a directory looking for `.claude/skills/`.
+ * Returns the `.claude/skills/` path if found, or null.
+ */
+function findSkillsDir(startDir: string): string | null {
+  let dir = startDir;
+  for (let i = 0; i < 10; i++) {
+    const candidate = join(dir, '.claude', 'skills');
+    if (existsSync(candidate)) return candidate;
+    const parent = dirname(dir);
+    if (parent === dir) break;
+    dir = parent;
+  }
+  return null;
+}
+
 /**
  * Load an agent prompt by name with layered resolution.
  *
- * @param agentName - The agent file name without extension (e.g., "review-code")
- * @param variables - Key-value map for {{variable}} substitution
- * @param boardDir  - Optional board directory for board-level overrides
+ * @param agentName  - The agent file name without extension (e.g., "review-code")
+ * @param variables  - Key-value map for {{variable}} substitution
+ * @param boardDir   - Optional board directory for board-level overrides
+ * @param workingDir - Optional working directory for project-level Skill resolution
  * @returns The interpolated prompt string, or null if no agent file found
  */
 export function loadAgentPrompt(
   agentName: string,
   variables: Record<string, string>,
   boardDir?: string | null,
+  workingDir?: string | null,
 ): string | null {
   const fileName = `${agentName}.md`;
 
   // 1. Board-level override
   if (boardDir) {
-    const boardAgentPath = join(boardDir, 'agents', fileName);
-    if (existsSync(boardAgentPath)) {
-      try {
-        const raw = readFileSync(boardAgentPath, 'utf-8');
-        return interpolate(stripFrontmatter(raw), variables);
-      } catch { /* fall through to system default */ }
+    const result = tryLoadFile(join(boardDir, 'agents', fileName), variables);
+    if (result) return result;
+  }
+
+  // 2. Project Skill: {workingDir}/.claude/skills/{agentName}/SKILL.md
+  if (workingDir) {
+    const skillsDir = findSkillsDir(workingDir);
+    if (skillsDir) {
+      const result = tryLoadFile(join(skillsDir, agentName, 'SKILL.md'), variables);
+      if (result) return result;
     }
   }
 
-  // 2. System default
-  const systemPath = join(SYSTEM_AGENTS_DIR, fileName);
+  // 3. System default
+  return tryLoadFile(join(SYSTEM_AGENTS_DIR, fileName), variables);
+}
+
+/**
+ * Load a Skill template body by name, stripping frontmatter.
+ * Looks in {workingDir}/.claude/skills/{skillName}/SKILL.md first,
+ * then falls back to the system agents directory.
+ *
+ * @param skillName  - The skill directory name (e.g., "code-review")
+ * @param workingDir - Working directory for project-level Skill resolution
+ * @returns Raw template body (no frontmatter), or null if not found
+ */
+export function loadSkillTemplate(skillName: string, workingDir?: string): string | null {
+  if (workingDir) {
+    const skillsDir = findSkillsDir(workingDir);
+    if (skillsDir) {
+      const path = join(skillsDir, skillName, 'SKILL.md');
+      if (existsSync(path)) {
+        try {
+          return stripFrontmatter(readFileSync(path, 'utf-8'));
+        } catch { /* fall through */ }
+      }
+    }
+  }
+
+  // Fallback: system agents directory
+  const systemPath = join(SYSTEM_AGENTS_DIR, `${skillName}.md`);
   if (existsSync(systemPath)) {
     try {
-      const raw = readFileSync(systemPath, 'utf-8');
-      return interpolate(stripFrontmatter(raw), variables);
+      return stripFrontmatter(readFileSync(systemPath, 'utf-8'));
     } catch { /* return null */ }
   }
 
   return null;
 }
+
+/**
+ * Load a Skill template and interpolate variables.
+ * Convenience wrapper combining loadSkillTemplate + interpolation.
+ */
+export function loadSkillPrompt(
+  skillName: string,
+  variables: Record<string, string>,
+  workingDir?: string,
+): string | null {
+  const template = loadSkillTemplate(skillName, workingDir);
+  if (!template) return null;
+  return interpolate(template, variables);
+}

package/server/services/plan/issue-retry.ts

@@ -76,6 +76,93 @@ export interface IssueRunnerConfig {
  * 2. Signal crash → fresh start with preserved tool results
  * 3. Premature completion → resume session with "continue"
  */
+/** Build the default "aborted" fallback result. */
+function abortedResult(bestResult: SessionResult | null): SessionResult {
+  return bestResult ?? {
+    completed: false, needsHandoff: false, totalTokens: 0, sessionId: '',
+    error: 'Execution stopped by user',
+  };
+}
+
+/** Create a HeadlessRunner configured for the current retry iteration. */
+function createRunner(
+  config: IssueRunnerConfig,
+  state: IssueRetryState,
+  useResume: boolean,
+  resumeSessionId: string | undefined,
+): HeadlessRunner {
+  return new HeadlessRunner({
+    workingDir: config.workingDir,
+    directPrompt: state.currentPrompt,
+    stallWarningMs: config.stallWarningMs,
+    stallKillMs: config.stallKillMs,
+    stallHardCapMs: config.stallHardCapMs,
+    stallMaxExtensions: config.stallMaxExtensions,
+    verbose: true,
+    continueSession: useResume,
+    claudeSessionId: resumeSessionId,
+    outputCallback: config.outputCallback,
+    onToolTimeout: (cp: ExecutionCheckpoint) => {
+      state.checkpoint = cp;
+    },
+    extraEnv: config.extraEnv,
+  });
+}
+
+/** Wire the abort signal to clean up the runner. Returns a cleanup function. */
+function wireAbortSignal(
+  runner: HeadlessRunner,
+  abortSignal: AbortSignal | undefined,
+): (() => void) | null {
+  if (!abortSignal) return null;
+
+  const abortHandler = () => { runner.cleanup(); };
+  abortSignal.addEventListener('abort', abortHandler, { once: true });
+  return () => abortSignal.removeEventListener('abort', abortHandler);
+}
+
+/**
+ * Run a single iteration: spawn runner, await result, evaluate retry.
+ * Returns { result, shouldRetry } — caller loops while shouldRetry is true.
+ * Returns null if aborted (caller should return abortedResult).
+ */
+async function runSingleAttempt(
+  config: IssueRunnerConfig,
+  state: IssueRetryState,
+): Promise<{ result: SessionResult; shouldRetry: boolean } | null> {
+  state.checkpoint = null;
+
+  const useResume = !!state.lastSessionId;
+  const resumeSessionId = state.lastSessionId;
+  state.lastSessionId = undefined;
+
+  const runner = createRunner(config, state, useResume, resumeSessionId);
+
+  if (config.abortSignal?.aborted) {
+    runner.cleanup();
+    return null;
+  }
+  const removeAbortListener = wireAbortSignal(runner, config.abortSignal);
+
+  const result = await runner.run();
+  removeAbortListener?.();
+
+  if (config.abortSignal?.aborted) return null;
+
+  // Track best result for fallback selection
+  if (!state.bestResult || scoreResult(result) > scoreResult(state.bestResult)) {
+    state.bestResult = result;
+  }
+
+  // Evaluate retry strategies in priority order
+  const shouldRetry =
+    tryToolTimeoutRetry(state, result, config) ||
+    trySignalCrashRetry(state, result, config) ||
+    await tryPrematureCompletionRetry(state, result, config);
+
+  return { result, shouldRetry };
+}
+
 export async function runIssueWithRetry(config: IssueRunnerConfig): Promise<SessionResult> {
   const state: IssueRetryState = {
     currentPrompt: config.prompt,
@@ -90,77 +177,15 @@ export async function runIssueWithRetry(config: IssueRunnerConfig): Promise<Sess
   let result: SessionResult | undefined;
 
   while (state.retryNumber <= MAX_ISSUE_RETRIES) {
-    // Check abort before starting a new attempt
-    if (config.abortSignal?.aborted) {
-      return state.bestResult ?? {
-        completed: false, needsHandoff: false, totalTokens: 0, sessionId: '',
-        error: 'Execution stopped by user',
-      };
-    }
-
-    // Clear checkpoint from prior iteration
-    state.checkpoint = null;
-
-    // Determine resume strategy
-    const useResume = !!state.lastSessionId;
-    const resumeSessionId = state.lastSessionId;
-    state.lastSessionId = undefined;
-
-    const runner = new HeadlessRunner({
-      workingDir: config.workingDir,
-      directPrompt: state.currentPrompt,
-      stallWarningMs: config.stallWarningMs,
-      stallKillMs: config.stallKillMs,
-      stallHardCapMs: config.stallHardCapMs,
-      stallMaxExtensions: config.stallMaxExtensions,
-      verbose: true,
-      continueSession: useResume,
-      claudeSessionId: resumeSessionId,
-      outputCallback: config.outputCallback,
-      onToolTimeout: (cp: ExecutionCheckpoint) => {
-        state.checkpoint = cp;
-      },
-      extraEnv: config.extraEnv,
-    });
-
-    // Wire abort signal to kill the runner's processes
-    const abortHandler = () => { runner.cleanup(); };
-    if (config.abortSignal) {
-      if (config.abortSignal.aborted) {
-        runner.cleanup();
-        return state.bestResult ?? {
-          completed: false, needsHandoff: false, totalTokens: 0, sessionId: '',
-          error: 'Execution stopped by user',
-        };
-      }
-      config.abortSignal.addEventListener('abort', abortHandler, { once: true });
-    }
-
-    result = await runner.run();
+    if (config.abortSignal?.aborted) return abortedResult(state.bestResult);
 
-    // Clean up abort listener
-    config.abortSignal?.removeEventListener('abort', abortHandler);
-
-    // If aborted during run, return immediately
-    if (config.abortSignal?.aborted) {
-      return state.bestResult ?? result ?? {
-        completed: false, needsHandoff: false, totalTokens: 0, sessionId: '',
-        error: 'Execution stopped by user',
-      };
-    }
-
-    // Track best result for fallback selection
-    if (!state.bestResult || scoreResult(result) > scoreResult(state.bestResult)) {
-      state.bestResult = result;
+    const attempt = await runSingleAttempt(config, state);
+    if (!attempt) {
+      return state.bestResult ?? result ?? abortedResult(null);
     }
 
-    // Evaluate retry strategies in priority order
-    if (tryToolTimeoutRetry(state, result, config)) continue;
-    if (trySignalCrashRetry(state, result, config)) continue;
-    if (await tryPrematureCompletionRetry(state, result, config)) continue;
-
-    // No retry needed — break out
-    break;
+    result = attempt.result;
+    if (!attempt.shouldRetry) break;
   }
 
   return result ?? state.bestResult ?? {

package/server/services/plan/review-gate.ts

@@ -50,7 +50,7 @@ export async function reviewIssue(options: ReviewIssueOptions): Promise<ReviewRe
   const issueType: ReviewResult['issueType'] = isCodeTask ? 'code' : 'non-code';
 
   try {
-    const prompt = buildReviewPrompt(issue, pmDir, outputPath, isCodeTask, reviewCriteria, boardDir);
+    const prompt = buildReviewPrompt(issue, pmDir, outputPath, isCodeTask, reviewCriteria, boardDir, workingDir);
 
     const runner = new HeadlessRunner({
       workingDir,
@@ -188,6 +188,7 @@ function buildReviewPrompt(
   isCodeTask: boolean,
   reviewCriteria?: string,
   boardDir?: string | null,
+  workingDir?: string,
 ): string {
   const criteria = issue.acceptanceCriteria
     .map(c => `- [${c.checked ? 'x' : ' '}] ${c.text}`)
@@ -205,115 +206,38 @@ function buildReviewPrompt(
       ? 'Read each modified file listed above'
       : 'Read the output file and issue spec at the paths above';
 
-    return loadAgentPrompt('review-custom', {
+    const result = loadAgentPrompt('review-custom', {
       issue_id: issue.id,
       issue_title: issue.title,
       context_section: contextSection,
       acceptance_criteria: criteriaStr,
       review_criteria: reviewCriteria,
       read_instruction: readInstruction,
-    }, boardDir) ?? buildCustomFallback(issue, contextSection, criteriaStr, reviewCriteria, readInstruction);
+    }, boardDir, workingDir);
+    if (result) return result;
   }
 
   if (isCodeTask) {
-    return loadAgentPrompt('review-code', {
+    const result = loadAgentPrompt('review-code', {
       issue_id: issue.id,
       issue_title: issue.title,
       files_modified: filesModified,
       acceptance_criteria: criteriaStr,
       output_path: outputPath,
-    }, boardDir) ?? buildCodeFallback(issue, filesModified, criteriaStr, outputPath);
+    }, boardDir, workingDir);
+    if (result) return result;
   }
 
-  return loadAgentPrompt('review-quality', {
+  const result = loadAgentPrompt('review-quality', {
     issue_id: issue.id,
     issue_title: issue.title,
     output_path: outputPath,
     issue_spec_path: issueSpecPath,
     acceptance_criteria: criteriaStr,
-  }, boardDir) ?? buildQualityFallback(issue, outputPath, issueSpecPath, criteriaStr);
-}
-
-// ── Hardcoded fallbacks (used when agent files are missing) ──────────
-
-function buildCodeFallback(issue: Issue, filesModified: string, criteria: string, outputPath: string): string {
-  return `You are a reviewer. Review the work done for issue ${issue.id}: ${issue.title}.
-
-## Files Modified
-${filesModified}
-
-## Acceptance Criteria
-${criteria}
-
-## Instructions
-1. Read each modified file listed above
-2. Check if all acceptance criteria are met by the changes
-3. Evaluate the quality of the changes:
-   - For source code files: look for obvious bugs, security vulnerabilities, or code quality issues
-   - For content files (markdown, docs, config, copy): check for accuracy, completeness, and appropriate structure
-4. Check if the output artifact exists at: ${outputPath}
-
-Output EXACTLY one JSON object on its own line (no markdown fencing):
-{"passed": true, "checks": [{"name": "criteria_met", "passed": true, "details": "..."}]}
-
-Include checks for: criteria_met, code_quality, no_obvious_bugs.`;
-}
-
-function buildQualityFallback(issue: Issue, outputPath: string, issueSpecPath: string, criteria: string): string {
-  return `You are a quality reviewer. Review the work done for issue ${issue.id}: ${issue.title}.
-
-## Output File
-${outputPath}
-
-## Issue Spec
-${issueSpecPath}
+  }, boardDir, workingDir);
+  if (result) return result;
 
-## Acceptance Criteria
-${criteria}
-
-## Instructions
-1. Read the output file at the path above
-2. Read the full issue spec to understand the original requirements and intent
-3. Evaluate the output against ALL of the following dimensions:
-
-### Acceptance Criteria
-- Are all acceptance criteria met? Check each one individually.
-
-### Content Quality
-- Is the content accurate, well-reasoned, and free of factual errors?
-- Is it written clearly with appropriate structure and organization?
-- Does it have sufficient depth and detail for its purpose?
-- Is the tone and style appropriate for the intended audience?
-
-### Completeness
-- Does the output fully address what was requested in the issue spec?
-- Are there obvious gaps, missing sections, or incomplete thoughts?
-- If the issue requested specific deliverables (e.g., a plan, analysis, document), are all deliverables present?
-
-Output EXACTLY one JSON object on its own line (no markdown fencing):
-{"passed": true, "checks": [{"name": "criteria_met", "passed": true, "details": "..."}]}
-
-Include checks for: criteria_met, output_quality, completeness.`;
+  // Should not reach here if Skills are installed, but provide a minimal fallback
+  return `You are a reviewer. Review the work done for issue ${issue.id}: ${issue.title}.\n\n## Acceptance Criteria\n${criteriaStr}\n\nOutput EXACTLY one JSON object on its own line (no markdown fencing):\n{"passed": true, "checks": [{"name": "criteria_met", "passed": true, "details": "..."}]}`;
 }
 
-function buildCustomFallback(issue: Issue, contextSection: string, criteria: string, reviewCriteria: string, readInstruction: string): string {
-  return `You are a reviewer. Review the work done for issue ${issue.id}: ${issue.title}.
-${contextSection}
-
-## Acceptance Criteria
-${criteria}
-
-## Review Criteria
-${reviewCriteria}
-
-## Instructions
-1. ${readInstruction}
-2. Check if all acceptance criteria are met — evaluate each criterion individually
-3. Evaluate thoroughly against the review criteria above
-4. Consider the overall quality of the work: does it fully address the issue's intent, is it well-structured, and is it ready to ship?
-
-Output EXACTLY one JSON object on its own line (no markdown fencing):
-{"passed": true, "checks": [{"name": "criteria_met", "passed": true, "details": "..."}]}
-
-Include checks for: criteria_met, review_criteria.`;
-}

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

@@ -1,6 +1,7 @@
 // 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 { handleGitCheckout, handleGitCreateBranch, handleGitDeleteBranch, handleGitListBranches } from './git-branch-handlers.js';
 import { handleGitCommitDiff, handleGitDiff, handleGitShowCommit } from './git-diff-handlers.js';
 import { handleGitDiscoverRepos, handleGitLog, handleGitSetDirectory } from './git-log-handlers.js';
@@ -195,25 +196,12 @@ async function handleGitCommitWithAI(ctx: HandlerContext, ws: WSContext, msg: We
     const diffResult = await executeGitCommand(['diff', '--cached'], workingDir);
     const logResult = await executeGitCommand(['log', '--oneline', '-5'], workingDir);
 
-    const prompt = `You are generating a git commit message for the following staged changes.
+    const recentCommits = logResult.stdout.trim() || 'No recent commits';
+    const stagedFiles = staged.map(f => `${f.status} ${f.path}`).join('\n');
+    const diff = truncateDiff(diffResult.stdout);
 
-RECENT COMMIT MESSAGES (for style reference):
-${logResult.stdout.trim() || 'No recent commits'}
-
-STAGED FILES:
-${staged.map(f => `${f.status} ${f.path}`).join('\n')}
-
-DIFF OF STAGED CHANGES:
-${truncateDiff(diffResult.stdout)}
-
-Generate a commit message following these rules:
-1. First line: imperative mood, max 72 characters (e.g., "Add user authentication", "Fix memory leak in parser")
-2. If the changes are complex, add a blank line then bullet points explaining the key changes
-3. Focus on the "why" not just the "what"
-4. Match the style of recent commits if possible
-5. No emojis unless the repo already uses them
-
-Respond with ONLY the commit message, nothing else.`;
+    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,

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

@@ -1,6 +1,7 @@
 // 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';
 import { detectGitProvider, executeGitCommand, spawnCheck, spawnHaikuWithPrompt, spawnWithOutput, stripCoauthorLines, truncateDiff } from './git-handlers.js';
 import type { HandlerContext } from './handler-context.js';
@@ -272,27 +273,11 @@ async function handleGitGeneratePRDescription(ctx: HandlerContext, ws: WSContext
     const diffResult = await executeGitCommand(['diff', `${compareRef}...HEAD`], workingDir);
     const statResult = await executeGitCommand(['diff', `${compareRef}...HEAD`, '--stat'], workingDir);
 
-    const prompt = `You are generating a pull request title and description for the following changes.
+    const filesChanged = statResult.exitCode === 0 ? statResult.stdout.trim() : '';
+    const diff = truncateDiff(diffResult.exitCode === 0 ? diffResult.stdout : '');
 
-COMMITS (${baseBranch}..HEAD):
-${commits}
-
-FILES CHANGED:
-${statResult.exitCode === 0 ? statResult.stdout.trim() : ''}
-
-DIFF:
-${truncateDiff(diffResult.exitCode === 0 ? diffResult.stdout : '')}
-
-Generate a pull request title and description following these rules:
-1. TITLE: First line must be the PR title — imperative mood, under 70 characters
-2. Leave a blank line after the title
-3. BODY: Write a concise description in markdown with:
-   - A "## Summary" section with 1-3 bullet points explaining what changed and why
-   - Optionally a "## Details" section if the changes are complex
-4. Focus on the "why" not just the "what"
-5. No emojis
-
-Respond with ONLY the title and description, nothing else.`;
+    const prompt = loadSkillPrompt('pr-description', { baseBranch, commits, filesChanged, diff }, workingDir)
+      ?? `You are generating a pull request title and description.\n\nCOMMITS (${baseBranch}..HEAD):\n${commits}\n\nFILES CHANGED:\n${filesChanged}\n\nDIFF:\n${diff}\n\nGenerate PR title (imperative, <70 chars) then body with ## Summary (1-3 bullets). No emojis. Respond with ONLY the title and description.`;
 
     const result = await spawnHaikuWithPrompt(
       prompt,

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

@@ -111,6 +111,35 @@ function sendChunkedResponse(
   }
 }
 
+/** Validate the incoming deploy HTTP request data. Returns an error response body string or null if valid. */
+function validateDeployRequest(
+  data: DeployHttpRequestData,
+): { status: number; body: string } | null {
+  if (!data?.requestId || !data?.method || !data?.url || !data?.port) {
+    return { status: 400, body: 'Bad Request: missing required fields (requestId, method, url, port)' };
+  }
+  if (data.headers && containsHeaderInjection(data.headers)) {
+    return { status: 400, body: 'Bad Request: headers contain null bytes or CRLF injection' };
+  }
+  if (data.headers && calculateHeaderSize(data.headers) > MAX_HEADER_SIZE_BYTES) {
+    return { status: 431, body: 'Request Header Fields Too Large: total headers exceed 16KB' };
+  }
+  return null;
+}
+
+/** Classify a fetch error into an HTTP status code and message. */
+function classifyFetchError(error: unknown): { status: number; body: string } {
+  if (error instanceof Error) {
+    if (error.name === 'AbortError') {
+      return { status: 504, body: 'Gateway Timeout' };
+    }
+    if (isConnectionRefused(error)) {
+      return { status: 502, body: 'Bad Gateway: target server is not running' };
+    }
+  }
+  return { status: 502, body: 'Bad Gateway' };
+}
+
 export async function handleDeployHttpRequest(
   ctx: HandlerContext,
   ws: WSContext,
@@ -118,34 +147,13 @@ export async function handleDeployHttpRequest(
 ): Promise<void> {
   const data = msg.data as DeployHttpRequestData;
 
-  if (!data?.requestId || !data?.method || !data?.url || !data?.port) {
+  const validationError = validateDeployRequest(data);
+  if (validationError) {
     sendDeployHttpResponse(ctx, ws, {
       requestId: data?.requestId || 'unknown',
-      status: 400,
-      headers: {},
-      body: 'Bad Request: missing required fields (requestId, method, url, port)',
-    });
-    return;
-  }
-
-  // Reject headers with null bytes or CRLF injection
-  if (data.headers && containsHeaderInjection(data.headers)) {
-    sendDeployHttpResponse(ctx, ws, {
-      requestId: data.requestId,
-      status: 400,
-      headers: {},
-      body: 'Bad Request: headers contain null bytes or CRLF injection',
-    });
-    return;
-  }
-
-  // Enforce header size limit
-  if (data.headers && calculateHeaderSize(data.headers) > MAX_HEADER_SIZE_BYTES) {
-    sendDeployHttpResponse(ctx, ws, {
-      requestId: data.requestId,
-      status: 431,
+      status: validationError.status,
       headers: {},
-      body: 'Request Header Fields Too Large: total headers exceed 16KB',
+      body: validationError.body,
     });
     return;
   }
@@ -201,18 +209,7 @@ export async function handleDeployHttpRequest(
       body: bodyBuffer.toString('utf-8'),
     });
   } catch (error: unknown) {
-    let status = 502;
-    let body = 'Bad Gateway';
-
-    if (error instanceof Error) {
-      if (error.name === 'AbortError') {
-        status = 504;
-        body = 'Gateway Timeout';
-      } else if (isConnectionRefused(error)) {
-        status = 502;
-        body = 'Bad Gateway: target server is not running';
-      }
-    }
+    const { status, body } = classifyFetchError(error);
 
     sendDeployHttpResponse(ctx, ws, {
       requestId: data.requestId,