mstro-app 0.4.29 → 0.4.33

package/server/services/pathUtils.ts

@@ -11,6 +11,54 @@
 import { existsSync, lstatSync, realpathSync } from 'node:fs';
 import { dirname, isAbsolute, normalize, relative, resolve } from 'node:path';
 
+/** Append a trailing separator to a directory path if not already present. */
+function ensureTrailingSep(dir: string): string {
+  return dir.endsWith('/') ? dir : `${dir}/`;
+}
+
+/** Resolve symlinks for an existing path. Returns the real path if it's a symlink. */
+function resolveExistingSymlink(resolvedPath: string): string {
+  const stat = lstatSync(resolvedPath);
+  if (stat.isSymbolicLink()) {
+    return realpathSync(resolvedPath);
+  }
+  return resolvedPath;
+}
+
+/**
+ * Validate that the parent directory of a non-existent path hasn't escaped
+ * the working directory via symlink. Returns an error result or null if valid.
+ */
+function validateParentSymlink(
+  resolvedPath: string,
+  normalizedWorkingDir: string,
+  targetPath: string,
+): PathValidationResult | null {
+  const parentDir = dirname(resolvedPath);
+  if (!existsSync(parentDir)) return null;
+
+  const realParent = realpathSync(parentDir);
+  const parentWithSep = ensureTrailingSep(normalizedWorkingDir);
+  if (realParent !== normalizedWorkingDir && !realParent.startsWith(parentWithSep)) {
+    console.error(
+      `[PathUtils] SECURITY: Symlink traversal in parent directory blocked. ` +
+      `Target: "${targetPath}", RealParent: "${realParent}", WorkingDir: "${normalizedWorkingDir}"`
+    );
+    return {
+      valid: false,
+      resolvedPath: '',
+      error: 'Access denied: parent directory resolves outside working directory'
+    };
+  }
+  return null;
+}
+
+/** Check whether a resolved path is within the working directory boundary. */
+function isPathWithinDir(resolvedPath: string, normalizedWorkingDir: string): boolean {
+  return resolvedPath === normalizedWorkingDir ||
+    resolvedPath.startsWith(ensureTrailingSep(normalizedWorkingDir));
+}
+
 export interface PathValidationResult {
   valid: boolean;
   resolvedPath: string;
@@ -34,12 +82,9 @@ export function validatePathWithinWorkingDir(
     const normalizedWorkingDir = resolve(workingDir);
 
     // Resolve the target path relative to working directory
-    let resolvedPath: string;
-    if (isAbsolute(targetPath)) {
-      resolvedPath = resolve(targetPath);
-    } else {
-      resolvedPath = resolve(normalizedWorkingDir, targetPath);
-    }
+    let resolvedPath = isAbsolute(targetPath)
+      ? resolve(targetPath)
+      : resolve(normalizedWorkingDir, targetPath);
 
     // Normalize to remove any .. or . segments
     resolvedPath = normalize(resolvedPath);
@@ -47,47 +92,15 @@ export function validatePathWithinWorkingDir(
     // Resolve symlinks to prevent symlink-based path traversal.
     // A symlink at /project/link -> /etc/passwd would pass the string
     // check below but actually read outside the working directory.
-    // For existing paths: resolve the full path via realpath.
-    // For new paths (create operations): resolve the parent directory.
     if (existsSync(resolvedPath)) {
-      // If the path itself is a symlink, resolve it to the real target
-      const stat = lstatSync(resolvedPath);
-      if (stat.isSymbolicLink()) {
-        resolvedPath = realpathSync(resolvedPath);
-      }
+      resolvedPath = resolveExistingSymlink(resolvedPath);
     } else {
       // Path doesn't exist yet (create operation) — validate the parent
-      const parentDir = dirname(resolvedPath);
-      if (existsSync(parentDir)) {
-        const realParent = realpathSync(parentDir);
-        const parentWithSep = normalizedWorkingDir.endsWith('/')
-          ? normalizedWorkingDir
-          : `${normalizedWorkingDir}/`;
-        if (realParent !== normalizedWorkingDir && !realParent.startsWith(parentWithSep)) {
-          console.error(
-            `[PathUtils] SECURITY: Symlink traversal in parent directory blocked. ` +
-            `Target: "${targetPath}", RealParent: "${realParent}", WorkingDir: "${normalizedWorkingDir}"`
-          );
-          return {
-            valid: false,
-            resolvedPath: '',
-            error: 'Access denied: parent directory resolves outside working directory'
-          };
-        }
-      }
+      const parentError = validateParentSymlink(resolvedPath, normalizedWorkingDir, targetPath);
+      if (parentError) return parentError;
     }
 
-    // Check if the resolved path starts with the working directory
-    // Add trailing separator to prevent partial matches (e.g., /home/user vs /home/username)
-    const workingDirWithSep = normalizedWorkingDir.endsWith('/')
-      ? normalizedWorkingDir
-      : `${normalizedWorkingDir}/`;
-
-    const isWithinWorkingDir =
-      resolvedPath === normalizedWorkingDir ||
-      resolvedPath.startsWith(workingDirWithSep);
-
-    if (!isWithinWorkingDir) {
+    if (!isPathWithinDir(resolvedPath, normalizedWorkingDir)) {
       // Log security violation for monitoring
       console.error(
         `[PathUtils] SECURITY: Path traversal attempt blocked. ` +

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).
@@ -15,6 +16,7 @@
 import { existsSync, readFileSync } from 'node:fs';
 import { dirname, join } from 'node:path';
 import { fileURLToPath } from 'node:url';
+import { findSkillsDir } from '../../utils/paths.js';
 
 const __dirname = dirname(fileURLToPath(import.meta.url));
 const SYSTEM_AGENTS_DIR = join(__dirname, 'agents');
@@ -34,40 +36,96 @@ 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;
+  }
+}
+
 /**
  * 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/file-explorer-handlers.ts

@@ -111,9 +111,30 @@ export function handleFileExplorerMessage(ctx: HandlerContext, ws: WSContext, ms
       handleRenameFile(ctx, ws, msg, tabId, workingDir);
     },
     notifyFileOpened: () => handleNotifyFileOpened(ctx, ws, msg, workingDir),
-    searchFileContents: () => handleSearchFileContents(ctx, ws, msg, tabId, workingDir),
+    searchFileContents: () => {
+      if (isSandboxed && msg.data?.query) {
+        const searchPath = msg.data.path || msg.data.dirPath;
+        if (searchPath) {
+          const validation = validatePathWithinWorkingDir(searchPath, workingDir);
+          if (!validation.valid) {
+            ctx.send(ws, { type: 'contentSearchError', tabId, data: { error: 'Sandboxed: search path outside project directory' } });
+            return;
+          }
+        }
+      }
+      handleSearchFileContents(ctx, ws, msg, tabId, workingDir);
+    },
     cancelSearch: () => handleCancelSearch(ctx, tabId),
-    findDefinition: () => handleFindDefinition(ctx, ws, msg, tabId, workingDir),
+    findDefinition: () => {
+      if (isSandboxed && msg.data?.filePath) {
+        const validation = validatePathWithinWorkingDir(msg.data.filePath, workingDir);
+        if (!validation.valid) {
+          ctx.send(ws, { type: 'definitionResult', tabId, data: { definitions: [], symbol: msg.data.symbol || '' } });
+          return;
+        }
+      }
+      handleFindDefinition(ctx, ws, msg, tabId, workingDir);
+    },
   };
   const handler = handlers[msg.type];
   if (!handler) return;