mstro-app 0.4.13 → 0.4.16

package/server/services/file-explorer-ops.ts

@@ -108,7 +108,8 @@ export function listDirectory(
 export function writeFile(
   filePath: string,
   content: string,
-  workingDir: string
+  workingDir: string,
+  encoding?: 'base64'
 ): FileOperationResult {
   if (containsDangerousPatterns(filePath)) {
     console.error(`[FileService] SECURITY: Dangerous pattern in path: "${filePath}"`)
@@ -133,7 +134,11 @@ export function writeFile(
       }
     }
 
-    writeFileSync(resolvedPath, content, 'utf-8')
+    if (encoding === 'base64') {
+      writeFileSync(resolvedPath, Buffer.from(content, 'base64'))
+    } else {
+      writeFileSync(resolvedPath, content, 'utf-8')
+    }
     return { success: true, path: resolvedPath.replace(`${workingDir}/`, '') }
   } catch (error: unknown) {
     console.error('[FileService] Error writing file:', error)

package/server/services/plan/composer.ts

@@ -129,6 +129,7 @@ export async function handlePlanPrompt(
   userPrompt: string,
   workingDir: string,
   boardId?: string,
+  sandboxed?: boolean,
 ): Promise<void> {
   const pmDir = resolvePmDir(workingDir) ?? defaultPmDir(workingDir);
   const projectContent = readFileOrEmpty(join(pmDir, 'project.md'));
@@ -237,7 +238,7 @@ Implementation guidance.
 - Give each child issue clear acceptance criteria and files to modify when possible
 - Set appropriate priorities (P0-P3) based on the issue's importance within the epic
 
-User request: ${userPrompt}`;
+User request: ${userPrompt}${sandboxed ? `\n\nIMPORTANT: This session has project-scoped access. You MUST NOT read, write, or access any files outside of "${workingDir}" and its subdirectories. All file operations (Read, Write, Edit, Glob, Grep, Bash) must target paths within this directory. Do not use absolute paths that escape this directory. Do not use "../" to access parent directories.` : ''}`;
 
   try {
     ctx.broadcastToAll({
@@ -248,6 +249,7 @@ User request: ${userPrompt}`;
     const runner = new HeadlessRunner({
       workingDir,
       directPrompt: enrichedPrompt,
+      sandboxed: sandboxed ?? false,
       outputCallback: (text: string) => {
         ctx.send(ws, {
           type: 'planPromptStreaming',

package/server/services/plan/executor.ts

@@ -69,6 +69,8 @@ export class PlanExecutor extends EventEmitter {
   private configInstaller: ConfigInstaller;
   /** Flag to prevent start() from clearing scope set by startBoard/startEpic */
   private _scopeSetByCall = false;
+  /** When true, HeadlessRunner instances run with sanitized env and project-scoped system prompt. */
+  private sandboxed = false;
   private metrics: ExecutionMetrics = {
     issuesCompleted: 0,
     issuesAttempted: 0,
@@ -85,6 +87,7 @@ export class PlanExecutor extends EventEmitter {
 
   getStatus(): ExecutionStatus { return this.status; }
   getMetrics(): ExecutionMetrics { return { ...this.metrics }; }
+  setSandboxed(value: boolean): void { this.sandboxed = value; }
 
   async startEpic(epicPath: string): Promise<void> {
     this.epicScope = epicPath;
@@ -240,14 +243,19 @@ export class PlanExecutor extends EventEmitter {
       outputPath,
     });
 
+    const sandboxPrompt = this.sandboxed
+      ? `\n\nIMPORTANT: This session has project-scoped access. You MUST NOT read, write, or access any files outside of "${this.workingDir}" and its subdirectories. All file operations (Read, Write, Edit, Glob, Grep, Bash) must target paths within this directory. Do not use absolute paths that escape this directory. Do not use "../" to access parent directories.`
+      : '';
+
     const runner = new HeadlessRunner({
       workingDir: this.workingDir,
-      directPrompt: prompt,
+      directPrompt: prompt + sandboxPrompt,
       stallWarningMs: ISSUE_STALL_WARNING_MS,
       stallKillMs: ISSUE_STALL_KILL_MS,
       stallHardCapMs: ISSUE_STALL_HARD_CAP_MS,
       stallMaxExtensions: ISSUE_STALL_MAX_EXTENSIONS,
       verbose: process.env.MSTRO_VERBOSE === '1',
+      sandboxed: this.sandboxed,
       outputCallback: (text: string) => {
         this.emit('output', { issueId: issue.id, text });
       },
@@ -363,6 +371,7 @@ export class PlanExecutor extends EventEmitter {
       outputPath,
       onOutput: (text) => this.emit('output', { issueId: issue.id, text }),
       logDir: this.boardDir ? join(this.boardDir, 'logs') : undefined,
+      reviewCriteria: this.getBoardReviewCriteria(),
     });
     persistReviewResult(reviewDir, issue, result);
 
@@ -407,6 +416,28 @@ export class PlanExecutor extends EventEmitter {
     }
   }
 
+  /** Read the board's custom review criteria, if set. */
+  private getBoardReviewCriteria(): string | undefined {
+    const pmDir = this.pmDir;
+    if (!pmDir) return undefined;
+
+    const effectiveBoardId = this.boardId ?? this.resolveActiveBoardId();
+    if (!effectiveBoardId) return undefined;
+
+    const boardMdPath = join(pmDir, 'boards', effectiveBoardId, 'board.md');
+    if (!existsSync(boardMdPath)) return undefined;
+
+    try {
+      const content = readFileSync(boardMdPath, 'utf-8');
+      const match = content.match(/^review_criteria:\s*"(.+)"/m);
+      if (!match) return undefined;
+      const raw = match[1].replace(/\\"/g, '"').replace(/\\n/g, '\n').trim();
+      return raw || undefined;
+    } catch {
+      return undefined;
+    }
+  }
+
   private pickReadyIssues(): Issue[] {
     const pmDir = this.pmDir;
     if (!pmDir) {

package/server/services/plan/parser-core.ts

@@ -397,6 +397,7 @@ export function parseBoard(content: string, filePath: string): Board {
     goal: String(fm.goal || sections.get('Goal') || ''),
     executionSummary,
     maxParallelAgents: clampParallelAgents(fm.max_parallel_agents),
+    reviewCriteria: String(fm.review_criteria || sections.get('Review Criteria') || '').replace(/\\n/g, '\n'),
     path: filePath,
   };
 }

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

@@ -31,6 +31,8 @@ export interface ReviewIssueOptions {
   onOutput?: (text: string) => void;
   /** Board-scoped log directory for execution logs. Falls back to global ~/.mstro/logs/headless/ */
   logDir?: string;
+  /** Custom board-level review criteria — replaces default review instructions when set */
+  reviewCriteria?: string;
 }
 
 /**
@@ -38,12 +40,12 @@ export interface ReviewIssueOptions {
  * Returns auto-pass on infrastructure failures to avoid blocking execution.
  */
 export async function reviewIssue(options: ReviewIssueOptions): Promise<ReviewResult> {
-  const { workingDir, issue, pmDir, outputPath, onOutput, logDir } = options;
+  const { workingDir, issue, pmDir, outputPath, onOutput, logDir, reviewCriteria } = options;
   const isCodeTask = issue.filesToModify.length > 0;
   const issueType: ReviewResult['issueType'] = isCodeTask ? 'code' : 'non-code';
 
   try {
-    const prompt = buildReviewPrompt(issue, pmDir, outputPath, isCodeTask);
+    const prompt = buildReviewPrompt(issue, pmDir, outputPath, isCodeTask, reviewCriteria);
 
     const runner = new HeadlessRunner({
       workingDir,
@@ -162,11 +164,34 @@ export function autoPassResult(issueId: string, issueType: ReviewResult['issueTy
 
 // ── Private helpers ─────────────────────────────────────────
 
-function buildReviewPrompt(issue: Issue, pmDir: string, outputPath: string, isCodeTask: boolean): string {
+function buildReviewPrompt(issue: Issue, pmDir: string, outputPath: string, isCodeTask: boolean, reviewCriteria?: string): string {
   const criteria = issue.acceptanceCriteria
     .map(c => `- [${c.checked ? 'x' : ' '}] ${c.text}`)
     .join('\n');
 
+  // When custom review criteria are set, use a generic review prompt
+  // that applies the user's criteria instead of assuming code review.
+  if (reviewCriteria) {
+    return `You are a reviewer. Review the work done for issue ${issue.id}: ${issue.title}.
+${isCodeTask ? `\n## Files Modified\n${issue.filesToModify.map(f => `- ${f}`).join('\n')}` : `\n## Output File\n${outputPath}\n\n## Issue Spec\n${join(pmDir, issue.path)}`}
+
+## Acceptance Criteria
+${criteria || 'No specific criteria defined.'}
+
+## Review Criteria
+${reviewCriteria}
+
+## Instructions
+1. ${isCodeTask ? 'Read each modified file listed above' : 'Read the output file and issue spec at the paths above'}
+2. Check if all acceptance criteria are met
+3. Evaluate against the review criteria above
+
+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.`;
+  }
+
   if (isCodeTask) {
     return `You are a code reviewer. Review the work done for issue ${issue.id}: ${issue.title}.
 

package/server/services/plan/types.ts

@@ -121,6 +121,8 @@ export interface Board {
   executionSummary: BoardExecutionSummary | null;
   /** Max parallel headless Claude Code instances per execution wave (default: 3) */
   maxParallelAgents: number;
+  /** Custom review criteria instructions — replaces default code-review prompt when set */
+  reviewCriteria: string;
   path: string;
 }
 

package/server/services/sandbox-utils.ts

@@ -58,7 +58,8 @@ const BLOCKED_KEYS = new Set([
  */
 export function sanitizeEnvForSandbox(
   env: NodeJS.ProcessEnv,
-  workingDir: string
+  workingDir: string,
+  options?: { overrideHome?: boolean }
 ): Record<string, string> {
   const result: Record<string, string> = {};
 
@@ -69,8 +70,11 @@ export function sanitizeEnvForSandbox(
     result[key] = value;
   }
 
-  // Override HOME to project directory so `cd ~` stays sandboxed
-  result.HOME = workingDir;
+  // Override HOME to project directory so `cd ~` stays sandboxed (e.g. terminals).
+  // Claude Code processes opt out (overrideHome: false) to preserve OAuth auth lookup.
+  if (options?.overrideHome !== false) {
+    result.HOME = workingDir;
+  }
   // Marker so scripts can detect sandboxed execution
   result.MSTRO_SANDBOXED = '1';
 

package/server/services/websocket/file-explorer-handlers.ts

@@ -132,7 +132,8 @@ function handleListDirectory(ctx: HandlerContext, ws: WSContext, msg: WebSocketM
 function handleWriteFile(ctx: HandlerContext, ws: WSContext, msg: WebSocketMessage, tabId: string, workingDir: string): void {
   if (!msg.data?.filePath) throw new Error('File path is required');
   if (msg.data.content === undefined) throw new Error('Content is required');
-  const result = writeFile(msg.data.filePath, msg.data.content, workingDir);
+  const encoding = msg.data.encoding === 'base64' ? 'base64' as const : undefined;
+  const result = writeFile(msg.data.filePath, msg.data.content, workingDir, encoding);
   sendFileResult(ctx, ws, 'fileWritten', tabId, result);
   if (result.success) {
     ctx.broadcastToOthers(ws, {

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

@@ -119,23 +119,29 @@ export async function handleGitSetDirectory(ctx: HandlerContext, ws: WSContext,
     return;
   }
 
-  // Security: validate path is within working directory to prevent traversal
+  // Security: validate path is within working directory OR is a valid worktree of the repo
   const resolvedDir = resolve(directory);
   const resolvedWorkingDir = resolve(workingDir);
-  if (!resolvedDir.startsWith(`${resolvedWorkingDir}/`) && resolvedDir !== resolvedWorkingDir) {
-    ctx.send(ws, { type: 'gitError', tabId, data: { error: 'Access denied: path outside project directory' } });
-    return;
+  const isWithinWorkingDir = resolvedDir.startsWith(`${resolvedWorkingDir}/`) || resolvedDir === resolvedWorkingDir;
+
+  if (!isWithinWorkingDir) {
+    // Check if the directory is a known worktree of this repo
+    const isWorktree = await isValidWorktreePath(resolvedDir, workingDir);
+    if (!isWorktree) {
+      ctx.send(ws, { type: 'gitError', tabId, data: { error: 'Access denied: path outside project directory' } });
+      return;
+    }
   }
 
-  const gitPath = join(directory, '.git');
+  const gitPath = join(resolvedDir, '.git');
   const isValid = existsSync(gitPath);
 
   if (isValid) {
-    ctx.gitDirectories.set(tabId, directory);
+    ctx.gitDirectories.set(tabId, resolvedDir);
   }
 
   const response: GitDirectorySetResponse = {
-    directory,
+    directory: resolvedDir,
     isValid,
   };
 
@@ -143,7 +149,22 @@ export async function handleGitSetDirectory(ctx: HandlerContext, ws: WSContext,
 
   if (isValid) {
     const { handleGitStatus } = await import('./git-handlers.js');
-    handleGitStatus(ctx, ws, tabId, directory);
-    handleGitLog(ctx, ws, { type: 'gitLog', data: { limit: 5 } }, tabId, directory);
+    handleGitStatus(ctx, ws, tabId, resolvedDir);
+    handleGitLog(ctx, ws, { type: 'gitLog', data: { limit: 5 } }, tabId, resolvedDir);
+  }
+}
+
+/** Check if a path is a registered worktree of the repo at workingDir */
+async function isValidWorktreePath(targetPath: string, workingDir: string): Promise<boolean> {
+  const result = await executeGitCommand(['worktree', 'list', '--porcelain'], workingDir);
+  if (result.exitCode !== 0) return false;
+
+  const resolvedTarget = resolve(targetPath);
+  for (const line of result.stdout.split('\n')) {
+    if (line.startsWith('worktree ')) {
+      const wtPath = resolve(line.slice(9).trim());
+      if (wtPath === resolvedTarget) return true;
+    }
   }
+  return false;
 }

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

@@ -156,6 +156,15 @@ async function handleGitWorktreeRemove(ctx: HandlerContext, ws: WSContext, msg:
 
     await executeGitCommand(['worktree', 'prune'], workingDir);
 
+    // Clean up gitDirectories entries for any tabs referencing the removed worktree
+    const resolvedWtPath = join(wtPath); // normalize
+    for (const [tid, dir] of ctx.gitDirectories) {
+      if (dir === resolvedWtPath || dir === wtPath) {
+        ctx.gitDirectories.delete(tid);
+        ctx.gitBranches.delete(tid);
+      }
+    }
+
     ctx.send(ws, { type: 'gitWorktreeRemoved', tabId, data: { path: wtPath } });
   } catch (error: unknown) {
     ctx.send(ws, { type: 'gitError', tabId, data: { error: error instanceof Error ? error.message : String(error) } });

package/server/services/websocket/handler.ts

@@ -178,14 +178,17 @@ export class WebSocketImproviseHandler implements HandlerContext {
     const domain = WebSocketImproviseHandler.DISPATCH[msg.type];
     if (!domain) throw new Error(`Unknown message type: ${msg.type}`);
 
+    // Resolve effective working directory: use worktree path if tab is on a worktree
+    const effectiveDir = this.gitDirectories.get(tabId) || workingDir;
+
     switch (domain) {
       case 'session':    return handleSessionMessage(this, ws, msg, tabId, permission);
       case 'history':    return handleHistoryMessage(this, ws, msg, tabId, workingDir);
-      case 'file':       return handleFileMessage(this, ws, msg, tabId, workingDir, permission);
+      case 'file':       return handleFileMessage(this, ws, msg, tabId, effectiveDir, permission);
       case 'terminal':   return handleTerminalMessage(this, ws, msg, tabId, workingDir, permission);
-      case 'fileExplorer': return handleFileExplorerMessage(this, ws, msg, tabId, workingDir, permission);
+      case 'fileExplorer': return handleFileExplorerMessage(this, ws, msg, tabId, effectiveDir, permission);
       case 'git':        return handleGitMessage(this, ws, msg, tabId, workingDir);
-      case 'quality':    return handleQualityMessage(this, ws, msg, tabId, workingDir);
+      case 'quality':    return handleQualityMessage(this, ws, msg, tabId, workingDir, permission);
       case 'plan':       return handlePlanMessage(this, ws, msg, tabId, workingDir, permission);
       case 'fileUpload': return this.handleFileUploadMessage(ws, msg, tabId, workingDir);
     }

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

@@ -24,7 +24,8 @@ export function handlePrompt(
     ctx.send(ws, { type: 'planError', data: { error: 'Prompt required' } });
     return;
   }
-  handlePlanPrompt(ctx, ws, prompt, workingDir, boardId).catch(error => {
+  const sandboxed = permission === 'control';
+  handlePlanPrompt(ctx, ws, prompt, workingDir, boardId, sandboxed).catch(error => {
     ctx.send(ws, {
       type: 'planError',
       data: { error: error instanceof Error ? error.message : String(error) },
@@ -100,6 +101,7 @@ export function handleExecute(
   if (denyIfViewOnly(ctx, ws, permission)) return;
 
   const executor = getExecutor(workingDir);
+  executor.setSandboxed(permission === 'control');
 
   if (executor.getStatus() === 'executing' || executor.getStatus() === 'starting') {
     ctx.send(ws, { type: 'planError', data: { error: 'Execution already in progress' } });
@@ -132,6 +134,7 @@ export function handleExecuteEpic(
   }
 
   const executor = getExecutor(workingDir);
+  executor.setSandboxed(permission === 'control');
 
   if (executor.getStatus() === 'executing' || executor.getStatus() === 'starting') {
     ctx.send(ws, { type: 'planError', data: { error: 'Execution already in progress' } });

package/server/services/websocket/plan-helpers.ts

@@ -39,7 +39,7 @@ export function formatYamlValue(value: unknown): string {
     if (value.length === 0) return '[]';
     return `[${value.map(v => typeof v === 'string' ? v : String(v)).join(', ')}]`;
   }
-  return `"${String(value).replace(/"/g, '\\"')}"`;
+  return `"${String(value).replace(/"/g, '\\"').replace(/\n/g, '\\n')}"`;
 }
 
 export function buildIssueMarkdown(

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

@@ -11,6 +11,7 @@
  */
 
 import { join } from 'node:path';
+import { validatePathWithinWorkingDir } from '../pathUtils.js';
 import type { HandlerContext } from './handler-context.js';
 import type { FindingForFix } from './quality-fix-agent.js';
 import { handleFixIssues } from './quality-fix-agent.js';
@@ -39,6 +40,26 @@ function resolvePath(workingDir: string, dirPath?: string): string {
   return join(workingDir, dirPath);
 }
 
+/**
+ * Resolve and validate a directory path for sandboxed users.
+ * Returns null if the path escapes the working directory.
+ */
+function resolveAndValidatePath(
+  workingDir: string,
+  dirPath: string | undefined,
+  isSandboxed: boolean,
+): { resolved: string; error?: string } {
+  const resolved = resolvePath(workingDir, dirPath);
+  if (isSandboxed) {
+    const validation = validatePathWithinWorkingDir(resolved, workingDir);
+    if (!validation.valid) {
+      return { resolved: '', error: validation.error || 'Path outside project directory' };
+    }
+    return { resolved: validation.resolvedPath };
+  }
+  return { resolved };
+}
+
 // ── Message router ────────────────────────────────────────────
 
 export function handleQualityMessage(
@@ -47,25 +68,33 @@ export function handleQualityMessage(
   msg: WebSocketMessage,
   _tabId: string,
   workingDir: string,
+  permission?: 'control' | 'view',
 ): void {
+  const isSandboxed = permission === 'control' || permission === 'view';
+  const sendPathError = (path: string, error: string) => {
+    ctx.send(ws, { type: 'qualityError', data: { path, error } });
+  };
+
   const handlers: Record<string, () => void> = {
-    qualityDetectTools: () => handleDetectTools(ctx, ws, msg, workingDir),
-    qualityScan: () => handleScan(ctx, ws, msg, workingDir),
-    qualityInstallTools: () => handleInstallTools(ctx, ws, msg, workingDir),
+    qualityDetectTools: () => handleDetectTools(ctx, ws, msg, workingDir, isSandboxed),
+    qualityScan: () => handleScan(ctx, ws, msg, workingDir, isSandboxed),
+    qualityInstallTools: () => handleInstallTools(ctx, ws, msg, workingDir, isSandboxed),
     qualityCodeReview: () => {
-      const dirPath = resolvePath(workingDir, msg.data?.path);
+      const { resolved: dirPath, error } = resolveAndValidatePath(workingDir, msg.data?.path, isSandboxed);
+      if (error) { sendPathError(msg.data?.path || '.', error); return; }
       const reportPath = msg.data?.path || '.';
       handleCodeReview(ctx, ws, reportPath, dirPath, workingDir, activeReviews, getPersistence);
     },
     qualityFixIssues: () => {
-      const dirPath = resolvePath(workingDir, msg.data?.path);
+      const { resolved: dirPath, error } = resolveAndValidatePath(workingDir, msg.data?.path, isSandboxed);
+      if (error) { sendPathError(msg.data?.path || '.', error); return; }
       const reportPath = msg.data?.path || '.';
       const section: string | undefined = msg.data?.section;
       const findings: FindingForFix[] = msg.data?.findings || [];
       handleFixIssues(ctx, ws, reportPath, dirPath, workingDir, section, findings, getPersistence);
     },
     qualityLoadState: () => handleLoadState(ctx, ws, workingDir),
-    qualitySaveDirectories: () => handleSaveDirectories(ctx, ws, msg, workingDir),
+    qualitySaveDirectories: () => handleSaveDirectories(ctx, ws, msg, workingDir, isSandboxed),
   };
 
   const handler = handlers[msg.type];
@@ -106,10 +135,26 @@ async function handleSaveDirectories(
   ws: WSContext,
   msg: WebSocketMessage,
   workingDir: string,
+  isSandboxed = false,
 ): Promise<void> {
   try {
     const persistence = getPersistence(workingDir);
     const directories: Array<{ path: string; label: string }> = msg.data?.directories || [];
+
+    // Validate all directory paths when sandboxed
+    if (isSandboxed) {
+      for (const dir of directories) {
+        const { error } = resolveAndValidatePath(workingDir, dir.path, true);
+        if (error) {
+          ctx.send(ws, {
+            type: 'qualityError',
+            data: { path: dir.path, error: `Cannot save directory: ${error}` },
+          });
+          return;
+        }
+      }
+    }
+
     persistence.saveConfig(directories);
   } catch (error) {
     ctx.send(ws, {
@@ -124,8 +169,13 @@ async function handleDetectTools(
   ws: WSContext,
   msg: WebSocketMessage,
   workingDir: string,
+  isSandboxed = false,
 ): Promise<void> {
-  const dirPath = resolvePath(workingDir, msg.data?.path);
+  const { resolved: dirPath, error: pathError } = resolveAndValidatePath(workingDir, msg.data?.path, isSandboxed);
+  if (pathError) {
+    ctx.send(ws, { type: 'qualityError', data: { path: msg.data?.path || '.', error: pathError } });
+    return;
+  }
   try {
     const { tools, ecosystem } = await detectTools(dirPath);
     ctx.send(ws, {
@@ -145,8 +195,13 @@ async function handleScan(
   ws: WSContext,
   msg: WebSocketMessage,
   workingDir: string,
+  isSandboxed = false,
 ): Promise<void> {
-  const dirPath = resolvePath(workingDir, msg.data?.path);
+  const { resolved: dirPath, error: pathError } = resolveAndValidatePath(workingDir, msg.data?.path, isSandboxed);
+  if (pathError) {
+    ctx.send(ws, { type: 'qualityError', data: { path: msg.data?.path || '.', error: pathError } });
+    return;
+  }
   const reportPath = msg.data?.path || '.';
 
   try {
@@ -184,8 +239,13 @@ async function handleInstallTools(
   ws: WSContext,
   msg: WebSocketMessage,
   workingDir: string,
+  isSandboxed = false,
 ): Promise<void> {
-  const dirPath = resolvePath(workingDir, msg.data?.path);
+  const { resolved: dirPath, error: pathError } = resolveAndValidatePath(workingDir, msg.data?.path, isSandboxed);
+  if (pathError) {
+    ctx.send(ws, { type: 'qualityError', data: { path: msg.data?.path || '.', error: pathError } });
+    return;
+  }
   const reportPath = msg.data?.path || '.';
   const toolNames: string[] | undefined = msg.data?.tools;
 

package/server/services/websocket/quality-persistence.ts

@@ -11,7 +11,7 @@
  *   .mstro/quality/history.json       — Score history entries for trend tracking
  */
 
-import { existsSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs';
+import { existsSync, mkdirSync, readdirSync, readFileSync, unlinkSync, writeFileSync } from 'node:fs';
 import { join } from 'node:path';
 import type { QualityResults } from './quality-service.js';
 
@@ -56,6 +56,7 @@ export interface QualityPersistedState {
 // ============================================================================
 
 const MAX_HISTORY_ENTRIES = 100;
+const MAX_REPORT_HISTORY_FILES = 200;
 
 function slugify(dirPath: string): string {
   if (dirPath === '.' || dirPath === './') return '_root';
@@ -94,15 +95,18 @@ function writeJson(filePath: string, data: unknown): void {
 export class QualityPersistence {
   private qualityDir: string;
   private reportsDir: string;
+  private reportHistoryDir: string;
   private configPath: string;
   private historyPath: string;
 
   constructor(workingDir: string) {
     this.qualityDir = join(workingDir, '.mstro', 'quality');
     this.reportsDir = join(this.qualityDir, 'reports');
+    this.reportHistoryDir = join(this.reportsDir, 'history');
     this.configPath = join(this.qualityDir, 'config.json');
     this.historyPath = join(this.qualityDir, 'history.json');
     ensureDir(this.reportsDir);
+    ensureDir(this.reportHistoryDir);
   }
 
   // ---- Config (directory list) ----
@@ -141,6 +145,12 @@ export class QualityPersistence {
     const slug = slugify(dirPath);
     const reportPath = join(this.reportsDir, `${slug}.json`);
     writeJson(reportPath, results);
+
+    // Archive timestamped copy for historical tracking
+    const ts = Date.now();
+    const archivePath = join(this.reportHistoryDir, `${ts}_${slug}.json`);
+    writeJson(archivePath, results);
+    this.pruneReportHistory();
   }
 
   loadAllReports(directories: QualityDirectoryConfig[]): Record<string, QualityResults> {
@@ -154,6 +164,19 @@ export class QualityPersistence {
     return reports;
   }
 
+  // ---- Report history pruning ----
+
+  private pruneReportHistory(): void {
+    try {
+      const files = readdirSync(this.reportHistoryDir).filter((f) => f.endsWith('.json')).sort();
+      if (files.length <= MAX_REPORT_HISTORY_FILES) return;
+      const toRemove = files.slice(0, files.length - MAX_REPORT_HISTORY_FILES);
+      for (const file of toRemove) {
+        try { unlinkSync(join(this.reportHistoryDir, file)); } catch { /* ignore */ }
+      }
+    } catch { /* directory may not exist yet */ }
+  }
+
   // ---- History (trend tracking) ----
 
   loadHistory(): QualityHistoryEntry[] {
@@ -219,7 +242,14 @@ export class QualityPersistence {
   saveCodeReview(dirPath: string, findings: Record<string, unknown>[], summary: string): void {
     const slug = slugify(dirPath);
     const reviewPath = join(this.reportsDir, `${slug}-review.json`);
-    writeJson(reviewPath, { findings, summary, timestamp: new Date().toISOString() });
+    const data = { findings, summary, timestamp: new Date().toISOString() };
+    writeJson(reviewPath, data);
+
+    // Archive timestamped copy for historical tracking
+    const ts = Date.now();
+    const archivePath = join(this.reportHistoryDir, `${ts}_${slug}-review.json`);
+    writeJson(archivePath, data);
+    this.pruneReportHistory();
   }
 
   // ---- Full state load ----