mstro-app 0.4.39 → 0.4.44

package/dist/server/services/plan/executor.js

@@ -15,12 +15,13 @@
  * - front-matter.ts          — YAML front matter field editing utility
  */
 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 { isAbsolute, join, relative, 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';
@@ -70,6 +71,15 @@ export class PlanExecutor extends EventEmitter {
         this.extraEnv = options?.extraEnv;
         this.configInstaller = new ConfigInstaller(workingDir);
     }
+    validateIssuePath(issuePath, baseDir) {
+        const resolvedBase = resolve(baseDir);
+        const resolvedFull = resolve(resolvedBase, issuePath);
+        const rel = relative(resolvedBase, resolvedFull);
+        if (rel === '' || rel.startsWith('..') || isAbsolute(rel)) {
+            throw new Error(`Invalid issue path: path traversal detected in "${issuePath}"`);
+        }
+        return resolvedFull;
+    }
     getStatus() { return this.status; }
     getMetrics() { return { ...this.metrics }; }
     async startEpic(epicPath) {
@@ -103,32 +113,38 @@ export class PlanExecutor extends EventEmitter {
         this.emit('statusChanged', this.status);
         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) {
             this.status = 'idle';
+            // Emit complete so clients can transition out of 'stopping' — metrics are broadcast by the handler.
+            this.emit('complete', 'Stopped by user');
         }
         else {
             this.status = 'complete';
         }
         this.emit('statusChanged', this.status);
     }
-    /** Run waves until done, paused, stopped, or stalled. Returns 'stalled' if zero-completion cap hit. */
+    /** Run waves until done, paused, stopped, or stalled. */
     async runWaveLoop() {
         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));
             if (completedCount > 0) {
                 consecutiveZeroCompletions = 0;
@@ -140,6 +156,19 @@ export class PlanExecutor extends EventEmitter {
         }
         return 'done';
     }
+    async hasDeadIssues() {
+        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() { this.shouldPause = true; }
     stop() {
         this.shouldStop = true;
@@ -166,10 +195,10 @@ export class PlanExecutor extends EventEmitter {
         this.emit('waveStarted', { issueIds: waveIds });
         // 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);
         const pmDir = this.pmDir;
@@ -196,13 +225,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;
     }
@@ -240,7 +269,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().
      */
-    finalizeWave(issues, waveStart, waveLabel) {
+    async finalizeWave(issues, waveStart, waveLabel) {
         try {
             reconcileState(this.workingDir, this.boardId ?? undefined);
             this.emit('stateUpdated');
@@ -263,7 +292,7 @@ export class PlanExecutor extends EventEmitter {
             });
         }
         try {
-            this.appendProgressEntry(issues, waveStart);
+            await this.appendProgressEntry(issues, waveStart);
         }
         catch (err) {
             this.emit('output', {
@@ -284,15 +313,15 @@ export class PlanExecutor extends EventEmitter {
             return 0;
         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++;
@@ -302,7 +331,7 @@ export class PlanExecutor extends EventEmitter {
                     }
                 }
                 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',
@@ -320,34 +349,40 @@ 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);
         const result = await reviewIssue({
-            workingDir: this.workingDir,
+            workingDir: this.executionDir || this.workingDir,
             issue,
             pmDir,
             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', {
@@ -363,13 +398,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.
      */
-    recoverStaleIssues() {
+    async recoverStaleIssues() {
         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;
@@ -379,7 +414,7 @@ export class PlanExecutor extends EventEmitter {
             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)`);
             }
         }
@@ -393,28 +428,28 @@ export class PlanExecutor extends EventEmitter {
     }
     // ── Helpers ──────────────────────────────────────────────────
     /** Read the board's maxParallelAgents setting, falling back to default. */
-    getBoardMaxParallelAgents() {
+    async getBoardMaxParallelAgents() {
         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. */
-    getBoardReviewCriteria() {
+    async getBoardReviewCriteria() {
         const pmDir = this.pmDir;
         if (!pmDir)
             return undefined;
@@ -425,18 +460,19 @@ 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;
         }
     }
-    pickReadyIssues() {
+    async pickReadyIssues() {
         const pmDir = this.pmDir;
         if (!pmDir) {
             this.emit('error', 'No PM directory found');
@@ -444,21 +480,27 @@ 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. */
-    loadBoardIssues(pmDir, boardId) {
+    async loadBoardIssues(pmDir, boardId) {
         const boardState = parseBoardDirectory(pmDir, boardId);
         if (!boardState) {
             this.emit('error', `Board not found: ${boardId}`);
@@ -469,7 +511,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})`);
@@ -491,18 +533,20 @@ export class PlanExecutor extends EventEmitter {
         return fullState.issues;
     }
     /** Activate a draft board by updating its status in board.md. */
-    activateBoard(pmDir, boardId) {
+    async activateBoard(pmDir, boardId) {
         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');
+            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 });
         }
-        catch { /* non-fatal — pickReadyIssues will re-check */ }
     }
     /** Check if all issues in a board are done and mark board as completed. */
-    tryCompleteBoardIfDone(pmDir, boardId, issues) {
+    async tryCompleteBoardIfDone(pmDir, boardId, issues) {
         const allDone = issues.length > 0 && issues.every(i => i.status === 'done' || i.status === 'cancelled');
         if (!allDone)
             return;
@@ -510,12 +554,14 @@ 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');
+            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 });
         }
-        catch { /* non-fatal */ }
     }
     resolveActiveBoardId() {
         const pmDir = this.pmDir;
@@ -542,58 +588,97 @@ export class PlanExecutor extends EventEmitter {
             return `${done}/${nonEpic.length} issues done, ${blocked} blocked by incomplete dependencies`;
         return this.epicScope ? 'All epic issues are done or blocked' : 'All work is done or blocked';
     }
-    revertIncompleteIssues(issues) {
+    /** Detect issues stuck in non-terminal states with no path to completion. */
+    detectDeadState(issues) {
+        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}` : ''}`;
+    }
+    async revertIncompleteIssues(issues) {
         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 });
+            }
+        }
+    }
+    async appendCancellationNote(issue, pmDir, reason) {
+        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 });
         }
     }
-    updateIssueFrontMatter(issuePath, newStatus) {
+    async updateIssueFrontMatter(issuePath, newStatus) {
         const pmDir = this.pmDir;
         if (!pmDir)
             return;
         try {
-            const fullPath = join(pmDir, issuePath);
-            setFrontMatterField(fullPath, 'status', newStatus);
-            // Check off all acceptance criteria when marking done
+            const fullPath = this.validateIssuePath(issuePath, pmDir);
+            await setFrontMatterFieldAsync(fullPath, 'status', newStatus);
             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');
+                    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 });
+        }
     }
-    ensureOutputDirs() {
+    async ensureOutputDirs() {
         if (this.boardDir) {
             const boardOutDir = join(this.boardDir, 'out');
             if (!existsSync(boardOutDir))
-                mkdirSync(boardOutDir, { recursive: true });
+                await mkdir(boardOutDir, { recursive: true });
         }
         else {
             const pmDir = this.pmDir;
             if (pmDir) {
                 const outDir = join(pmDir, 'out');
                 if (!existsSync(outDir))
-                    mkdirSync(outDir, { recursive: true });
+                    await mkdir(outDir, { recursive: true });
             }
         }
     }
-    appendProgressEntry(issues, waveStart) {
+    async appendProgressEntry(issues, waveStart) {
         const pmDir = this.pmDir;
         if (!pmDir)
             return;
-        // Board-scoped progress log
         const progressPath = this.boardDir
             ? join(this.boardDir, 'progress.md')
             : join(pmDir, 'progress.md');
@@ -603,7 +688,7 @@ export class PlanExecutor extends EventEmitter {
         const failed = [];
         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);
@@ -627,19 +712,20 @@ export class PlanExecutor extends EventEmitter {
             lines.push(`- **Failed**: ${failed.join(', ')}`);
         }
         lines.push('');
-        this.writeProgressLines(progressPath, lines);
+        await this.writeProgressLines(progressPath, lines);
     }
-    writeProgressLines(filePath, lines) {
+    async writeProgressLines(filePath, lines) {
         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. */
     resolveBoardDir() {