mstro-app 0.4.39 → 0.4.43

package/server/services/plan/executor.ts

@@ -17,12 +17,13 @@
  */
 
 import { EventEmitter } from 'node:events';
-import { existsSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs';
-import { join } from 'node:path';
+import { existsSync, readFileSync } from 'node:fs';
+import { appendFile, mkdir, readFile, writeFile } from 'node:fs/promises';
+import { join, resolve } from 'node:path';
 import { runWithFileLogger } from '../../cli/headless/headless-logger.js';
 import { ConfigInstaller } from './config-installer.js';
 import { resolveReadyToWork } from './dependency-resolver.js';
-import { checkAllAcceptanceCriteria, replaceFrontMatterField, setFrontMatterField } from './front-matter.js';
+import { checkAllAcceptanceCriteria, replaceFrontMatterField, setFrontMatterFieldAsync } from './front-matter.js';
 import { buildIssuePrompt } from './issue-prompt-builder.js';
 import { runIssueWithRetry } from './issue-retry.js';
 import { listExistingDocs, publishOutputs, resolveOutputPath } from './output-manager.js';
@@ -90,6 +91,14 @@ export class PlanExecutor extends EventEmitter {
     this.configInstaller = new ConfigInstaller(workingDir);
   }
 
+  private validateIssuePath(issuePath: string, baseDir: string): string {
+    const fullPath = join(baseDir, issuePath);
+    if (!resolve(fullPath).startsWith(resolve(baseDir))) {
+      throw new Error(`Invalid issue path: path traversal detected in "${issuePath}"`);
+    }
+    return fullPath;
+  }
+
   getStatus(): ExecutionStatus { return this.status; }
   getMetrics(): ExecutionMetrics { return { ...this.metrics }; }
 
@@ -129,15 +138,17 @@ export class PlanExecutor extends EventEmitter {
     this.pmDir = resolvePmDir(this.workingDir);
     this.boardDir = this.resolveBoardDir();
 
-    this.recoverStaleIssues();
+    await this.recoverStaleIssues();
 
     const stallResult = await this.runWaveLoop();
 
     this.metrics.totalDuration = Date.now() - startTime;
 
-    if (stallResult === 'stalled') {
+    if (stallResult === 'stalled' || stallResult === 'dead') {
       this.status = 'error';
-      this.emit('error', `Execution stalled: ${MAX_CONSECUTIVE_EMPTY_WAVES} consecutive waves completed zero issues. Issues may be stuck in review or failing repeatedly.`);
+      if (stallResult === 'stalled') {
+        this.emit('error', `Execution stalled: ${MAX_CONSECUTIVE_EMPTY_WAVES} consecutive waves completed zero issues. Issues may be stuck in review or failing repeatedly.`);
+      }
     } else if (this.shouldPause) {
       this.status = 'paused';
     } else if (this.shouldStop) {
@@ -148,14 +159,17 @@ export class PlanExecutor extends EventEmitter {
     this.emit('statusChanged', this.status);
   }
 
-  /** Run waves until done, paused, stopped, or stalled. Returns 'stalled' if zero-completion cap hit. */
-  private async runWaveLoop(): Promise<'done' | 'stalled'> {
+  /** Run waves until done, paused, stopped, or stalled. */
+  private async runWaveLoop(): Promise<'done' | 'stalled' | 'dead'> {
     let consecutiveZeroCompletions = 0;
-    const maxParallel = this.getBoardMaxParallelAgents();
+    const maxParallel = await this.getBoardMaxParallelAgents();
 
     while (!this.shouldStop && !this.shouldPause) {
-      const readyIssues = this.pickReadyIssues();
-      if (readyIssues.length === 0) break;
+      const readyIssues = await this.pickReadyIssues();
+      if (readyIssues.length === 0) {
+        // pickReadyIssues emits 'error' for dead state, 'complete' otherwise — check if dead
+        return await this.hasDeadIssues() ? 'dead' : 'done';
+      }
 
       const completedCount = await this.executeWave(readyIssues.slice(0, maxParallel));
 
@@ -169,6 +183,18 @@ export class PlanExecutor extends EventEmitter {
     return 'done';
   }
 
+  private async hasDeadIssues(): Promise<boolean> {
+    const pmDir = this.pmDir;
+    if (!pmDir) return false;
+    const effectiveBoardId = this.boardId ?? this.resolveActiveBoardId();
+    const issues = effectiveBoardId
+      ? await this.loadBoardIssues(pmDir, effectiveBoardId)
+      : this.loadProjectIssues();
+    if (!issues) return false;
+    const terminalStatuses = new Set(['done', 'cancelled']);
+    return issues.some(i => i.type !== 'epic' && !terminalStatuses.has(i.status) && i.status !== 'todo');
+  }
+
   pause(): void { this.shouldPause = true; }
   stop(): void {
     this.shouldStop = true;
@@ -199,11 +225,11 @@ export class PlanExecutor extends EventEmitter {
     // Create abort controller for this wave — stop() will abort it
     this.waveAbortController = new AbortController();
 
-    this.ensureOutputDirs();
+    await this.ensureOutputDirs();
     this.configInstaller.installPermissions();
 
     for (const issue of issues) {
-      this.updateIssueFrontMatter(issue.path, 'in_progress');
+      await this.updateIssueFrontMatter(issue.path, 'in_progress');
     }
 
     const existingDocs = listExistingDocs(this.workingDir, this.boardDir);
@@ -234,13 +260,13 @@ export class PlanExecutor extends EventEmitter {
         issueIds: waveIds,
         error: error instanceof Error ? error.message : String(error),
       });
-      this.revertIncompleteIssues(issues);
+      await this.revertIncompleteIssues(issues);
     } finally {
       this.configInstaller.uninstallPermissions();
     }
 
     this.waveAbortController = null;
-    this.finalizeWave(issues, waveStart, waveLabel);
+    await this.finalizeWave(issues, waveStart, waveLabel);
     this.metrics.currentWaveIds = [];
     return completedCount;
   }
@@ -288,7 +314,7 @@ export class PlanExecutor extends EventEmitter {
    * Post-wave operations wrapped individually so a failure in one
    * doesn't prevent the others or kill the while loop in start().
    */
-  private finalizeWave(issues: Issue[], waveStart: number, waveLabel: string): void {
+  private async finalizeWave(issues: Issue[], waveStart: number, waveLabel: string): Promise<void> {
     try {
       reconcileState(this.workingDir, this.boardId ?? undefined);
       this.emit('stateUpdated');
@@ -311,7 +337,7 @@ export class PlanExecutor extends EventEmitter {
     }
 
     try {
-      this.appendProgressEntry(issues, waveStart);
+      await this.appendProgressEntry(issues, waveStart);
     } catch (err) {
       this.emit('output', {
         issueId: waveLabel,
@@ -334,16 +360,16 @@ export class PlanExecutor extends EventEmitter {
     let completed = 0;
 
     for (const issue of issues) {
-      const fullPath = join(pmDir, issue.path);
+      const fullPath = this.validateIssuePath(issue.path, pmDir);
       try {
-        const content = readFileSync(fullPath, 'utf-8');
+        const content = await readFile(fullPath, 'utf-8');
         const statusMatch = content.match(/^status:\s*(\S+)/m);
         const currentStatus = statusMatch?.[1] ?? 'unknown';
 
         if (currentStatus === 'in_review' || currentStatus === 'done') {
           if (issue.reviewGate === 'none') {
             // Skip review gate — mark done directly
-            this.updateIssueFrontMatter(issue.path, 'done');
+            await this.updateIssueFrontMatter(issue.path, 'done');
             this.metrics.issuesCompleted++;
             this.emit('issueCompleted', issue);
             completed++;
@@ -351,7 +377,7 @@ export class PlanExecutor extends EventEmitter {
             completed += await this.runReviewGate(issue, pmDir);
           }
         } else {
-          this.updateIssueFrontMatter(issue.path, issue.status);
+          await this.updateIssueFrontMatter(issue.path, issue.status);
           this.emit('issueError', {
             issueId: issue.id,
             error: 'Issue did not complete during wave execution',
@@ -370,13 +396,19 @@ export class PlanExecutor extends EventEmitter {
     const reviewDir = this.boardDir ?? pmDir;
     const attempts = getReviewAttemptCount(reviewDir, issue);
     if (attempts >= MAX_REVIEW_ATTEMPTS) {
-      this.updateIssueFrontMatter(issue.path, 'in_review');
+      await this.updateIssueFrontMatter(issue.path, 'cancelled');
+      await this.appendCancellationNote(issue, pmDir, `Cancelled after ${MAX_REVIEW_ATTEMPTS} failed reviews — issue may need restructuring`);
       this.emit('reviewProgress', { issueId: issue.id, status: 'max_attempts' });
-      this.emit('output', { issueId: issue.id, text: 'Review: max attempts reached, keeping in review' });
+      this.emit('issueAbandoned', {
+        issueId: issue.id,
+        reason: `Review failed ${MAX_REVIEW_ATTEMPTS} times — cancelled to unblock dependents`,
+        attempts,
+      });
+      this.emit('output', { issueId: issue.id, text: `Review: max attempts reached, cancelling issue to unblock dependents` });
       return 0;
     }
 
-    this.updateIssueFrontMatter(issue.path, 'in_review');
+    await this.updateIssueFrontMatter(issue.path, 'in_review');
     this.emit('reviewProgress', { issueId: issue.id, status: 'reviewing' });
 
     const outputPath = resolveOutputPath(issue, this.workingDir, this.boardDir);
@@ -387,21 +419,21 @@ 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(),
+      reviewCriteria: await this.getBoardReviewCriteria(),
       boardDir: this.boardDir,
       extraEnv: this.extraEnv,
     });
     persistReviewResult(reviewDir, issue, result);
 
     if (result.passed) {
-      this.updateIssueFrontMatter(issue.path, 'done');
+      await this.updateIssueFrontMatter(issue.path, 'done');
       this.metrics.issuesCompleted++;
       this.emit('reviewProgress', { issueId: issue.id, status: 'passed' });
       this.emit('issueCompleted', issue);
       return 1;
     }
 
-    this.updateIssueFrontMatter(issue.path, 'todo');
+    await this.updateIssueFrontMatter(issue.path, 'todo');
     appendReviewFeedback(pmDir, issue, result);
     this.emit('reviewProgress', { issueId: issue.id, status: 'failed' });
     this.emit('issueError', {
@@ -419,13 +451,13 @@ export class PlanExecutor extends EventEmitter {
    * these issues block the dependency graph and cause the executor to
    * find zero ready issues, making "Implement" appear to do nothing.
    */
-  private recoverStaleIssues(): void {
+  private async recoverStaleIssues(): Promise<void> {
     const pmDir = this.pmDir;
     if (!pmDir) return;
 
     const effectiveBoardId = this.boardId ?? this.resolveActiveBoardId();
     const issues = effectiveBoardId
-      ? this.loadBoardIssues(pmDir, effectiveBoardId)
+      ? await this.loadBoardIssues(pmDir, effectiveBoardId)
       : this.loadProjectIssues();
 
     if (!issues) return;
@@ -436,7 +468,7 @@ export class PlanExecutor extends EventEmitter {
     for (const issue of issues) {
       if (issue.type === 'epic') continue;
       if (staleStatuses.has(issue.status)) {
-        this.updateIssueFrontMatter(issue.path, 'todo');
+        await this.updateIssueFrontMatter(issue.path, 'todo');
         recovered.push(`${issue.id} (${issue.status} → todo)`);
       }
     }
@@ -453,28 +485,28 @@ export class PlanExecutor extends EventEmitter {
   // ── Helpers ──────────────────────────────────────────────────
 
   /** Read the board's maxParallelAgents setting, falling back to default. */
-  private getBoardMaxParallelAgents(): number {
+  private async getBoardMaxParallelAgents(): Promise<number> {
     const pmDir = this.pmDir;
     if (!pmDir) return DEFAULT_MAX_PARALLEL_AGENTS;
 
     const effectiveBoardId = this.boardId ?? this.resolveActiveBoardId();
     if (!effectiveBoardId) return DEFAULT_MAX_PARALLEL_AGENTS;
 
-    // Read only board.md — avoids parsing STATE.md and all backlog issues just for one setting
     const boardMdPath = join(pmDir, 'boards', effectiveBoardId, 'board.md');
     if (!existsSync(boardMdPath)) return DEFAULT_MAX_PARALLEL_AGENTS;
 
     try {
-      const content = readFileSync(boardMdPath, 'utf-8');
+      const content = await readFile(boardMdPath, 'utf-8');
       const match = content.match(/^max_parallel_agents:\s*(\d+)/m);
       return match ? Math.max(1, Math.min(Number(match[1]), 10)) : DEFAULT_MAX_PARALLEL_AGENTS;
-    } catch {
+    } catch (err) {
+      this.emit('output', { issueId: 'system', text: `Warning: failed to read board max_parallel_agents: ${err instanceof Error ? err.message : String(err)}`, boardId: this.boardId ?? null });
       return DEFAULT_MAX_PARALLEL_AGENTS;
     }
   }
 
   /** Read the board's custom review criteria, if set. */
-  private getBoardReviewCriteria(): string | undefined {
+  private async getBoardReviewCriteria(): Promise<string | undefined> {
     const pmDir = this.pmDir;
     if (!pmDir) return undefined;
 
@@ -485,17 +517,18 @@ export class PlanExecutor extends EventEmitter {
     if (!existsSync(boardMdPath)) return undefined;
 
     try {
-      const content = readFileSync(boardMdPath, 'utf-8');
+      const content = await readFile(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 {
+    } catch (err) {
+      this.emit('output', { issueId: 'system', text: `Warning: failed to read board review criteria: ${err instanceof Error ? err.message : String(err)}`, boardId: this.boardId ?? null });
       return undefined;
     }
   }
 
-  private pickReadyIssues(): Issue[] {
+  private async pickReadyIssues(): Promise<Issue[]> {
     const pmDir = this.pmDir;
     if (!pmDir) {
       this.emit('error', 'No PM directory found');
@@ -504,23 +537,28 @@ export class PlanExecutor extends EventEmitter {
 
     const effectiveBoardId = this.boardId ?? this.resolveActiveBoardId();
     const issues = effectiveBoardId
-      ? this.loadBoardIssues(pmDir, effectiveBoardId)
+      ? await this.loadBoardIssues(pmDir, effectiveBoardId)
       : this.loadProjectIssues();
 
     if (!issues) return [];
 
     const readyIssues = resolveReadyToWork(issues, this.epicScope ?? undefined);
     if (readyIssues.length === 0) {
-      this.emit('complete', this.buildCompletionReason(issues));
-      if (effectiveBoardId) {
-        this.tryCompleteBoardIfDone(pmDir, effectiveBoardId, issues);
+      const deadState = this.detectDeadState(issues);
+      if (deadState) {
+        this.emit('error', deadState);
+      } else {
+        this.emit('complete', this.buildCompletionReason(issues));
+        if (effectiveBoardId) {
+          await this.tryCompleteBoardIfDone(pmDir, effectiveBoardId, issues);
+        }
       }
     }
     return readyIssues;
   }
 
   /** Load issues from a specific board, auto-activating draft boards. Returns null on error. */
-  private loadBoardIssues(pmDir: string, boardId: string): Issue[] | null {
+  private async loadBoardIssues(pmDir: string, boardId: string): Promise<Issue[] | null> {
     const boardState = parseBoardDirectory(pmDir, boardId);
     if (!boardState) {
       this.emit('error', `Board not found: ${boardId}`);
@@ -531,7 +569,7 @@ export class PlanExecutor extends EventEmitter {
       return null;
     }
     if (boardState.board.status === 'draft') {
-      this.activateBoard(pmDir, boardId);
+      await this.activateBoard(pmDir, boardId);
     } else if (boardState.board.status !== 'active') {
       this.emit('error', `Board ${boardId} is not active (status: ${boardState.board.status})`);
       return null;
@@ -554,17 +592,19 @@ export class PlanExecutor extends EventEmitter {
   }
 
   /** Activate a draft board by updating its status in board.md. */
-  private activateBoard(pmDir: string, boardId: string): void {
+  private async activateBoard(pmDir: string, boardId: string): Promise<void> {
     const boardMdPath = join(pmDir, 'boards', boardId, 'board.md');
     if (!existsSync(boardMdPath)) return;
     try {
-      const content = readFileSync(boardMdPath, 'utf-8');
-      writeFileSync(boardMdPath, replaceFrontMatterField(content, 'status', 'active'), 'utf-8');
-    } catch { /* non-fatal — pickReadyIssues will re-check */ }
+      const content = await readFile(boardMdPath, 'utf-8');
+      await writeFile(boardMdPath, replaceFrontMatterField(content, 'status', 'active'), 'utf-8');
+    } catch (err) {
+      this.emit('output', { issueId: 'system', text: `Warning: failed to activate board ${boardId}: ${err instanceof Error ? err.message : String(err)}`, boardId: this.boardId ?? null });
+    }
   }
 
   /** Check if all issues in a board are done and mark board as completed. */
-  private tryCompleteBoardIfDone(pmDir: string, boardId: string, issues: Issue[]): void {
+  private async tryCompleteBoardIfDone(pmDir: string, boardId: string, issues: Issue[]): Promise<void> {
     const allDone = issues.length > 0 && issues.every(i => i.status === 'done' || i.status === 'cancelled');
     if (!allDone) return;
 
@@ -572,11 +612,13 @@ export class PlanExecutor extends EventEmitter {
     if (!existsSync(boardMdPath)) return;
 
     try {
-      let content = readFileSync(boardMdPath, 'utf-8');
+      let content = await readFile(boardMdPath, 'utf-8');
       content = replaceFrontMatterField(content, 'status', 'completed');
       content = replaceFrontMatterField(content, 'completed_at', `"${new Date().toISOString()}"`);
-      writeFileSync(boardMdPath, content, 'utf-8');
-    } catch { /* non-fatal */ }
+      await writeFile(boardMdPath, content, 'utf-8');
+    } catch (err) {
+      this.emit('output', { issueId: 'system', text: `Warning: failed to mark board ${boardId} as completed: ${err instanceof Error ? err.message : String(err)}`, boardId: this.boardId ?? null });
+    }
   }
 
   private resolveActiveBoardId(): string | null {
@@ -601,54 +643,95 @@ export class PlanExecutor extends EventEmitter {
     return this.epicScope ? 'All epic issues are done or blocked' : 'All work is done or blocked';
   }
 
-  private revertIncompleteIssues(issues: Issue[]): void {
+  /** Detect issues stuck in non-terminal states with no path to completion. */
+  private detectDeadState(issues: Issue[]): string | null {
+    const nonEpic = issues.filter(i => i.type !== 'epic');
+    const terminalStatuses = new Set(['done', 'cancelled']);
+    const stuck = nonEpic.filter(i => !terminalStatuses.has(i.status) && i.status !== 'todo');
+
+    if (stuck.length === 0) return null;
+
+    const stuckIds = stuck.map(i => `${i.id} (${i.status})`).join(', ');
+
+    const issueByPath = new Map(issues.map(i => [i.path, i]));
+    const blockedByStuck = nonEpic.filter(i => {
+      if (i.status !== 'todo') return false;
+      return i.blockedBy.some(bp => {
+        const blocker = issueByPath.get(bp);
+        return blocker && !terminalStatuses.has(blocker.status);
+      });
+    });
+    const blockedIds = blockedByStuck.map(i => i.id).join(', ');
+
+    return `Board stuck: ${stuckIds} cannot progress${blockedIds ? `. Blocking: ${blockedIds}` : ''}`;
+  }
+
+  private async revertIncompleteIssues(issues: Issue[]): Promise<void> {
     const pmDir = this.pmDir;
     if (!pmDir) return;
     for (const issue of issues) {
-      const fullPath = join(pmDir, issue.path);
+      const fullPath = this.validateIssuePath(issue.path, pmDir);
       try {
-        const content = readFileSync(fullPath, 'utf-8');
+        const content = await readFile(fullPath, 'utf-8');
         if (content.match(/^status:\s*in_progress$/m)) {
-          this.updateIssueFrontMatter(issue.path, issue.status);
+          await this.updateIssueFrontMatter(issue.path, issue.status);
         }
-      } catch { /* file may be gone */ }
+      } catch (err) {
+        this.emit('output', { issueId: issue.id, text: `Warning: failed to revert issue status: ${err instanceof Error ? err.message : String(err)}`, boardId: this.boardId ?? null });
+      }
     }
   }
 
-  private updateIssueFrontMatter(issuePath: string, newStatus: string): void {
+  private async appendCancellationNote(issue: Issue, pmDir: string, reason: string): Promise<void> {
+    const fullPath = this.validateIssuePath(issue.path, pmDir);
+    try {
+      let content = await readFile(fullPath, 'utf-8');
+      const entry = `- Cancelled (${new Date().toISOString().split('T')[0]}): ${reason}`;
+      if (content.includes('## Activity')) {
+        content = content.replace(/## Activity/, `## Activity\n${entry}`);
+      } else {
+        content += `\n\n## Activity\n${entry}`;
+      }
+      await writeFile(fullPath, content, 'utf-8');
+    } catch (err) {
+      this.emit('output', { issueId: issue.id, text: `Warning: failed to append cancellation note: ${err instanceof Error ? err.message : String(err)}`, boardId: this.boardId ?? null });
+    }
+  }
+
+  private async updateIssueFrontMatter(issuePath: string, newStatus: string): Promise<void> {
     const pmDir = this.pmDir;
     if (!pmDir) return;
     try {
-      const fullPath = join(pmDir, issuePath);
-      setFrontMatterField(fullPath, 'status', newStatus);
+      const fullPath = this.validateIssuePath(issuePath, pmDir);
+      await setFrontMatterFieldAsync(fullPath, 'status', newStatus);
 
-      // Check off all acceptance criteria when marking done
       if (newStatus === 'done') {
-        const content = readFileSync(fullPath, 'utf-8');
+        const content = await readFile(fullPath, 'utf-8');
         const updated = checkAllAcceptanceCriteria(content);
-        if (updated !== content) writeFileSync(fullPath, updated, 'utf-8');
+        if (updated !== content) await writeFile(fullPath, updated, 'utf-8');
       }
-    } catch { /* file may have been moved */ }
+    } catch (err) {
+      this.emit('output', { issueId: 'system', text: `Warning: failed to update issue front matter for ${issuePath}: ${err instanceof Error ? err.message : String(err)}`, boardId: this.boardId ?? null });
+    }
   }
 
-  private ensureOutputDirs(): void {
+  private async ensureOutputDirs(): Promise<void> {
     if (this.boardDir) {
       const boardOutDir = join(this.boardDir, 'out');
-      if (!existsSync(boardOutDir)) mkdirSync(boardOutDir, { recursive: true });
+      if (!existsSync(boardOutDir)) await mkdir(boardOutDir, { recursive: true });
     } else {
       const pmDir = this.pmDir;
       if (pmDir) {
         const outDir = join(pmDir, 'out');
-        if (!existsSync(outDir)) mkdirSync(outDir, { recursive: true });
+        if (!existsSync(outDir)) await mkdir(outDir, { recursive: true });
       }
     }
   }
 
-  private appendProgressEntry(issues: Issue[], waveStart: number): void {
+  private async appendProgressEntry(issues: Issue[], waveStart: number): Promise<void> {
     const pmDir = this.pmDir;
     if (!pmDir) return;
 
-    // Board-scoped progress log
     const progressPath = this.boardDir
       ? join(this.boardDir, 'progress.md')
       : join(pmDir, 'progress.md');
@@ -660,7 +743,7 @@ export class PlanExecutor extends EventEmitter {
     const failed: string[] = [];
     for (const issue of issues) {
       try {
-        const content = readFileSync(join(pmDir, issue.path), 'utf-8');
+        const content = await readFile(this.validateIssuePath(issue.path, pmDir), 'utf-8');
         const statusMatch = content.match(/^status:\s*(\S+)/m);
         if (statusMatch?.[1] === 'done') {
           completed.push(issue.id);
@@ -684,18 +767,19 @@ export class PlanExecutor extends EventEmitter {
     }
     lines.push('');
 
-    this.writeProgressLines(progressPath, lines);
+    await this.writeProgressLines(progressPath, lines);
   }
 
-  private writeProgressLines(filePath: string, lines: string[]): void {
+  private async writeProgressLines(filePath: string, lines: string[]): Promise<void> {
     try {
       if (existsSync(filePath)) {
-        const existing = readFileSync(filePath, 'utf-8');
-        writeFileSync(filePath, `${existing.trimEnd()}\n${lines.join('\n')}`, 'utf-8');
+        await appendFile(filePath, `\n${lines.join('\n')}`, 'utf-8');
       } else {
-        writeFileSync(filePath, `# Board Progress\n${lines.join('\n')}`, 'utf-8');
+        await writeFile(filePath, `# Board Progress\n${lines.join('\n')}`, 'utf-8');
       }
-    } catch { /* non-fatal */ }
+    } catch (err) {
+      this.emit('output', { issueId: 'system', text: `Warning: failed to write progress log: ${err instanceof Error ? err.message : String(err)}`, boardId: this.boardId ?? null });
+    }
   }
 
   /** Resolve the active board's directory path for outputs, reviews, and progress. */

package/server/services/plan/front-matter.ts

@@ -10,6 +10,7 @@
  */
 
 import { readFileSync, writeFileSync } from 'node:fs';
+import { readFile, writeFile } from 'node:fs/promises';
 
 /**
  * Replace a field value in a raw YAML string (no --- delimiters).
@@ -47,6 +48,12 @@ export function setFrontMatterField(filePath: string, field: string, value: stri
   writeFileSync(filePath, updated, 'utf-8');
 }
 
+export async function setFrontMatterFieldAsync(filePath: string, field: string, value: string): Promise<void> {
+  const content = await readFile(filePath, 'utf-8');
+  const updated = replaceFrontMatterField(content, field, value);
+  await writeFile(filePath, updated, 'utf-8');
+}
+
 /**
  * Check off all unchecked acceptance criteria checkboxes in a markdown string.
  * Only modifies checkboxes within the "## Acceptance Criteria" section.

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

@@ -0,0 +1,21 @@
+// Copyright (c) 2025-present Mstro, Inc. All rights reserved.
+// Licensed under the MIT License. See LICENSE file for details.
+
+import type { Issue } from './types.js';
+
+/**
+ * Determine whether an issue is a code task (modifies source files) or a
+ * document task (produces written output like research, design, plans).
+ *
+ * Uses the issue's `outputType` field when explicitly set. Falls back to
+ * inferring from `filesToModify` — entries prefixed with "Output:" are
+ * output path hints, not source files to edit.
+ */
+export function resolveIsCodeTask(issue: Issue): boolean {
+  if (issue.outputType === 'code') return true;
+  if (issue.outputType === 'document') return false;
+
+  // auto: infer from filesToModify, filtering out Output:-prefixed entries
+  const codeFiles = issue.filesToModify.filter(f => !f.match(/^Output:/i));
+  return codeFiles.length > 0;
+}

package/server/services/plan/issue-prompt-builder.ts

@@ -9,6 +9,7 @@
  */
 
 import { join } from 'node:path';
+import { resolveIsCodeTask } from './issue-classification.js';
 import type { Issue } from './types.js';
 
 export interface IssuePromptOptions {
@@ -33,8 +34,11 @@ export function buildIssuePrompt(options: IssuePromptOptions): string {
     .map(c => `- [${c.checked ? 'x' : ' '}] ${c.text}`)
     .join('\n');
 
-  const files = issue.filesToModify.length > 0
-    ? `\n## Files to Modify\n${issue.filesToModify.map(f => `- ${f}`).join('\n')}`
+  const isCode = resolveIsCodeTask(issue);
+  const codeFiles = isCode ? issue.filesToModify.filter(f => !f.match(/^Output:/i)) : [];
+
+  const files = codeFiles.length > 0
+    ? `\n## Files to Modify\n${codeFiles.map(f => `- ${f}`).join('\n')}`
     : '';
 
   const predecessorDocs = resolvePredecessorDocs(issue, existingDocs);
@@ -69,7 +73,7 @@ ${files}${predecessorSection}
 ## Your Task
 
 1. Read the full issue spec at ${pmDir ? join(pmDir, issue.path) : issue.path}
-${issue.filesToModify.length > 0 ? `2. **Implement the code changes** in the source files listed under "Files to Modify". You MUST edit or create the actual source code files — the acceptance criteria describe what the code must do, not what to document. Read each target file first, then make the changes using Edit or Write.
+${isCode ? `2. **Implement the code changes** in the source files listed under "Files to Modify". You MUST edit or create the actual source code files — the acceptance criteria describe what the code must do, not what to document. Read each target file first, then make the changes using Edit or Write.
 3. After implementation, write a brief summary of what you changed to **${outputPath}**${predecessorDocs.length > 0 ? ' — this is the handoff artifact for downstream issues' : ''}
 4. After writing output, update the issue front matter: change \`status: in_progress\` to \`status: in_review\`` : `2. Execute all acceptance criteria listed above
 3. Write your output and results to **${outputPath}** — this is the handoff artifact for downstream issues
@@ -79,7 +83,7 @@ ${issue.filesToModify.length > 0 ? `2. **Implement the code changes** in the sou
 
 - Stay within this issue's scope. Do not modify files outside your assigned scope.
 - The orchestrator manages STATE.md separately — do not edit STATE.md.
-${issue.filesToModify.length > 0 ? `- The output file is a summary of work done, NOT a substitute for implementation. You must modify the actual source code files listed in "Files to Modify". A review gate will verify the source files were changed.` : `- Write all significant output to ${outDir}/ so downstream issues can reference it.`}
+${isCode ? `- The output file is a summary of work done, NOT a substitute for implementation. You must modify the actual source code files listed in "Files to Modify". A review gate will verify the source files were changed.` : `- Write all significant output to ${outDir}/ so downstream issues can reference it.`}
 - If you cannot complete the issue, leave status as \`in_progress\` and document what blocked you in the output file.`;
 }