fix(core): Fix race condition in workflow state persistence (#1339)

Co-authored-by: Claude <noreply@anthropic.com>

.changeset/nice-laws-help.md

@@ -0,0 +1,7 @@
+---
+"task-master-ai": patch
+---
+
+Fixed MCP server sometimes crashing when getting into the commit step of autopilot
+
+- autopilot now persists state consistently through the whole flow

apps/cli/src/commands/autopilot/commit.command.ts

@@ -3,16 +3,8 @@
  */
 
 import { Command } from 'commander';
-import { WorkflowOrchestrator } from '@tm/core';
-import {
-	AutopilotBaseOptions,
-	hasWorkflowState,
-	loadWorkflowState,
-	createGitAdapter,
-	createCommitMessageGenerator,
-	OutputFormatter,
-	saveWorkflowState
-} from './shared.js';
+import { WorkflowService, GitAdapter, CommitMessageGenerator } from '@tm/core';
+import { AutopilotBaseOptions, OutputFormatter } from './shared.js';
 
 type CommitOptions = AutopilotBaseOptions;
 
@@ -43,47 +35,41 @@ export class CommitCommand extends Command {
 		const formatter = new OutputFormatter(mergedOptions.json || false);
 
 		try {
-			// Check for workflow state
-			const hasState = await hasWorkflowState(mergedOptions.projectRoot!);
-			if (!hasState) {
+			const projectRoot = mergedOptions.projectRoot!;
+
+			// Create workflow service (manages WorkflowStateManager internally)
+			const workflowService = new WorkflowService(projectRoot);
+
+			// Check if workflow exists
+			if (!(await workflowService.hasWorkflow())) {
 				formatter.error('No active workflow', {
 					suggestion: 'Start a workflow with: autopilot start <taskId>'
 				});
 				process.exit(1);
 			}
 
-			// Load state
-			const state = await loadWorkflowState(mergedOptions.projectRoot!);
-			if (!state) {
-				formatter.error('Failed to load workflow state');
-				process.exit(1);
-			}
-
-			const orchestrator = new WorkflowOrchestrator(state.context);
-			orchestrator.restoreState(state);
-			orchestrator.enableAutoPersist(async (newState) => {
-				await saveWorkflowState(mergedOptions.projectRoot!, newState);
-			});
+			// Resume workflow (loads state with single WorkflowStateManager instance)
+			await workflowService.resumeWorkflow();
+			const status = workflowService.getStatus();
+			const workflowContext = workflowService.getContext();
 
 			// Verify in COMMIT phase
-			const tddPhase = orchestrator.getCurrentTDDPhase();
-			if (tddPhase !== 'COMMIT') {
+			if (status.tddPhase !== 'COMMIT') {
 				formatter.error('Not in COMMIT phase', {
-					currentPhase: tddPhase || orchestrator.getCurrentPhase(),
+					currentPhase: status.tddPhase || status.phase,
 					suggestion: 'Complete RED and GREEN phases first'
 				});
 				process.exit(1);
 			}
 
-			// Get current subtask
-			const currentSubtask = orchestrator.getCurrentSubtask();
-			if (!currentSubtask) {
+			// Verify there's an active subtask
+			if (!status.currentSubtask) {
 				formatter.error('No current subtask');
 				process.exit(1);
 			}
 
 			// Initialize git adapter
-			const gitAdapter = createGitAdapter(mergedOptions.projectRoot!);
+			const gitAdapter = new GitAdapter(projectRoot);
 			await gitAdapter.ensureGitRepository();
 
 			// Check for staged changes
@@ -95,20 +81,20 @@ export class CommitCommand extends Command {
 			}
 
 			// Get changed files for scope detection
-			const status = await gitAdapter.getStatus();
-			const changedFiles = [...status.staged, ...status.modified];
+			const gitStatus = await gitAdapter.getStatus();
+			const changedFiles = [...gitStatus.staged, ...gitStatus.modified];
 
 			// Generate commit message
-			const messageGenerator = createCommitMessageGenerator();
-			const testResults = state.context.lastTestResults;
+			const messageGenerator = new CommitMessageGenerator();
+			const testResults = workflowContext.lastTestResults;
 
 			const commitMessage = messageGenerator.generateMessage({
 				type: 'feat',
-				description: currentSubtask.title,
+				description: status.currentSubtask.title,
 				changedFiles,
-				taskId: state.context.taskId,
-				phase: 'TDD',
-				tag: (state.context.metadata.tag as string) || undefined,
+				taskId: status.taskId,
+				phase: status.tddPhase,
+				tag: (workflowContext.metadata.tag as string) || undefined,
 				testsPassing: testResults?.passed,
 				testsFailing: testResults?.failed,
 				coveragePercent: undefined // Could be added if available
@@ -117,8 +103,8 @@ export class CommitCommand extends Command {
 			// Create commit with metadata
 			await gitAdapter.createCommit(commitMessage, {
 				metadata: {
-					taskId: state.context.taskId,
-					subtaskId: currentSubtask.id,
+					taskId: status.taskId,
+					subtaskId: status.currentSubtask.id,
 					phase: 'COMMIT',
 					tddCycle: 'complete'
 				}
@@ -127,36 +113,24 @@ export class CommitCommand extends Command {
 			// Get commit info
 			const lastCommit = await gitAdapter.getLastCommit();
 
-			// Complete COMMIT phase (this marks subtask as completed)
-			orchestrator.transition({ type: 'COMMIT_COMPLETE' });
+			// Complete COMMIT phase and advance workflow
+			// This handles all transitions internally with a single WorkflowStateManager
+			const newStatus = await workflowService.commit();
 
-			// Check if should advance to next subtask
-			const progress = orchestrator.getProgress();
-			if (progress.current < progress.total) {
-				orchestrator.transition({ type: 'SUBTASK_COMPLETE' });
-			} else {
-				// All subtasks complete
-				orchestrator.transition({ type: 'ALL_SUBTASKS_COMPLETE' });
-			}
+			const isComplete = newStatus.phase === 'COMPLETE';
 
 			// Output success
 			formatter.success('Commit created', {
 				commitHash: lastCommit.hash.substring(0, 7),
 				message: commitMessage.split('\n')[0], // First line only
 				subtask: {
-					id: currentSubtask.id,
-					title: currentSubtask.title,
-					status: currentSubtask.status
+					id: status.currentSubtask.id,
+					title: status.currentSubtask.title
 				},
-				progress: {
-					completed: progress.completed,
-					total: progress.total,
-					percentage: progress.percentage
-				},
-				nextAction:
-					progress.completed < progress.total
-						? 'Start next subtask with RED phase'
-						: 'All subtasks complete. Run: autopilot status'
+				progress: newStatus.progress,
+				nextAction: isComplete
+					? 'All subtasks complete. Run: autopilot status'
+					: 'Start next subtask with RED phase'
 			});
 		} catch (error) {
 			formatter.error((error as Error).message);

package-lock.json

@@ -64,6 +64,7 @@
 				"open": "^10.2.0",
 				"ora": "^8.2.0",
 				"simple-git": "^3.28.0",
+				"steno": "^4.0.2",
 				"uuid": "^11.1.0",
 				"zod": "^4.1.11"
 			},
@@ -25049,6 +25050,18 @@
 				"url": "https://github.com/sponsors/sindresorhus"
 			}
 		},
+		"node_modules/steno": {
+			"version": "4.0.2",
+			"resolved": "https://registry.npmjs.org/steno/-/steno-4.0.2.tgz",
+			"integrity": "sha512-yhPIQXjrlt1xv7dyPQg2P17URmXbuM5pdGkpiMB3RenprfiBlvK415Lctfe0eshk90oA7/tNq7WEiMK8RSP39A==",
+			"license": "MIT",
+			"engines": {
+				"node": ">=18"
+			},
+			"funding": {
+				"url": "https://github.com/sponsors/typicode"
+			}
+		},
 		"node_modules/stop-iteration-iterator": {
 			"version": "1.1.0",
 			"dev": true,
@@ -28500,6 +28513,7 @@
 				"@supabase/supabase-js": "^2.57.4",
 				"fs-extra": "^11.3.2",
 				"simple-git": "^3.28.0",
+				"steno": "^4.0.2",
 				"zod": "^4.1.11"
 			},
 			"devDependencies": {

package.json

@@ -102,6 +102,7 @@
 		"open": "^10.2.0",
 		"ora": "^8.2.0",
 		"simple-git": "^3.28.0",
+		"steno": "^4.0.2",
 		"uuid": "^11.1.0",
 		"zod": "^4.1.11"
 	},

packages/tm-core/package.json

@@ -33,6 +33,7 @@
 		"@supabase/supabase-js": "^2.57.4",
 		"fs-extra": "^11.3.2",
 		"simple-git": "^3.28.0",
+		"steno": "^4.0.2",
 		"zod": "^4.1.11"
 	},
 	"devDependencies": {

packages/tm-core/src/modules/workflow/managers/workflow-state-manager.ts

@@ -9,6 +9,7 @@
 import fs from 'node:fs/promises';
 import path from 'node:path';
 import os from 'node:os';
+import { Writer } from 'steno';
 import type { WorkflowState } from '../types.js';
 import { getLogger } from '../../../common/logger/index.js';
 
@@ -28,6 +29,8 @@ export class WorkflowStateManager {
 	private readonly sessionDir: string;
 	private maxBackups: number;
 	private readonly logger = getLogger('WorkflowStateManager');
+	private writer: Writer | null = null;
+	private writerInitPromise: Promise<void> | null = null;
 
 	constructor(projectRoot: string, maxBackups = 5) {
 		this.projectRoot = path.resolve(projectRoot);
@@ -69,6 +72,31 @@ export class WorkflowStateManager {
 		return sanitized;
 	}
 
+	/**
+	 * Ensure the steno Writer is initialized
+	 * This ensures the session directory exists before creating the writer
+	 */
+	private async ensureWriter(): Promise<void> {
+		if (this.writer) {
+			return;
+		}
+
+		// If another call is already initializing, wait for it
+		if (this.writerInitPromise) {
+			await this.writerInitPromise;
+			return;
+		}
+
+		this.writerInitPromise = (async () => {
+			// Ensure session directory exists before creating writer
+			await fs.mkdir(this.sessionDir, { recursive: true });
+			this.writer = new Writer(this.statePath);
+		})();
+
+		await this.writerInitPromise;
+		this.writerInitPromise = null;
+	}
+
 	/**
 	 * Check if workflow state exists
 	 */
@@ -98,11 +126,12 @@ export class WorkflowStateManager {
 
 	/**
 	 * Save workflow state to disk
+	 * Uses steno for atomic writes and automatic queueing of concurrent saves
 	 */
 	async save(state: WorkflowState): Promise<void> {
 		try {
-			// Ensure session directory exists
-			await fs.mkdir(this.sessionDir, { recursive: true });
+			// Ensure writer is initialized (creates directory if needed)
+			await this.ensureWriter();
 
 			// Serialize and validate JSON
 			const jsonContent = JSON.stringify(state, null, 2);
@@ -115,10 +144,8 @@ export class WorkflowStateManager {
 				throw new Error('Failed to generate valid JSON from workflow state');
 			}
 
-			// Write state atomically with newline at end
-			const tempPath = `${this.statePath}.tmp`;
-			await fs.writeFile(tempPath, jsonContent + '\n', 'utf-8');
-			await fs.rename(tempPath, this.statePath);
+			// Write using steno (handles queuing and atomic writes automatically)
+			await this.writer!.write(jsonContent + '\n');
 
 			this.logger.debug(`Saved workflow state (${jsonContent.length} bytes)`);
 		} catch (error: any) {

packages/tm-core/src/modules/workflow/orchestrators/workflow-orchestrator.ts

@@ -98,7 +98,7 @@ export class WorkflowOrchestrator {
 	/**
 	 * Transition to next state based on event
 	 */
-	transition(event: WorkflowEvent): void {
+	async transition(event: WorkflowEvent): Promise<void> {
 		// Check if workflow is aborted
 		if (this.aborted && event.type !== 'ABORT') {
 			throw new Error('Workflow has been aborted');
@@ -107,26 +107,26 @@ export class WorkflowOrchestrator {
 		// Handle special events that work across all phases
 		if (event.type === 'ERROR') {
 			this.handleError(event.error);
-			void this.triggerAutoPersist();
+			await this.triggerAutoPersist();
 			return;
 		}
 
 		if (event.type === 'ABORT') {
 			this.aborted = true;
-			void this.triggerAutoPersist();
+			await this.triggerAutoPersist();
 			return;
 		}
 
 		if (event.type === 'RETRY') {
 			this.handleRetry();
-			void this.triggerAutoPersist();
+			await this.triggerAutoPersist();
 			return;
 		}
 
 		// Handle TDD phase transitions within SUBTASK_LOOP
 		if (this.currentPhase === 'SUBTASK_LOOP') {
-			this.handleTDDPhaseTransition(event);
-			void this.triggerAutoPersist();
+			await this.handleTDDPhaseTransition(event);
+			await this.triggerAutoPersist();
 			return;
 		}
 
@@ -143,13 +143,13 @@ export class WorkflowOrchestrator {
 
 		// Execute transition
 		this.executeTransition(validTransition, event);
-		void this.triggerAutoPersist();
+		await this.triggerAutoPersist();
 	}
 
 	/**
 	 * Handle TDD phase transitions (RED -> GREEN -> COMMIT)
 	 */
-	private handleTDDPhaseTransition(event: WorkflowEvent): void {
+	private async handleTDDPhaseTransition(event: WorkflowEvent): Promise<void> {
 		const currentTDD = this.context.currentTDDPhase || 'RED';
 
 		switch (event.type) {
@@ -201,7 +201,7 @@ export class WorkflowOrchestrator {
 						this.emit('subtask:started');
 					} else {
 						// All subtasks complete, transition to FINALIZE
-						this.transition({ type: 'ALL_SUBTASKS_COMPLETE' });
+						await this.transition({ type: 'ALL_SUBTASKS_COMPLETE' });
 					}
 					break;
 				}
@@ -272,7 +272,7 @@ export class WorkflowOrchestrator {
 					this.emit('subtask:started');
 				} else {
 					// All subtasks complete, transition to FINALIZE
-					this.transition({ type: 'ALL_SUBTASKS_COMPLETE' });
+					await this.transition({ type: 'ALL_SUBTASKS_COMPLETE' });
 				}
 				break;
 

packages/tm-core/src/modules/workflow/services/workflow.service.ts

@@ -168,7 +168,7 @@ export class WorkflowService {
 		this.activityLogger.start();
 
 		// Transition through PREFLIGHT and BRANCH_SETUP phases
-		this.orchestrator.transition({ type: 'PREFLIGHT_COMPLETE' });
+		await this.orchestrator.transition({ type: 'PREFLIGHT_COMPLETE' });
 
 		// Create git branch with descriptive name
 		const branchName = this.generateBranchName(taskId, taskTitle, tag);
@@ -181,7 +181,7 @@ export class WorkflowService {
 		}
 
 		// Transition to SUBTASK_LOOP with RED phase
-		this.orchestrator.transition({
+		await this.orchestrator.transition({
 			type: 'BRANCH_CREATED',
 			branchName
 		});
@@ -363,13 +363,13 @@ export class WorkflowService {
 		// Transition based on current phase
 		switch (tddPhase) {
 			case 'RED':
-				this.orchestrator.transition({
+				await this.orchestrator.transition({
 					type: 'RED_PHASE_COMPLETE',
 					testResults
 				});
 				break;
 			case 'GREEN':
-				this.orchestrator.transition({
+				await this.orchestrator.transition({
 					type: 'GREEN_PHASE_COMPLETE',
 					testResults
 				});
@@ -402,17 +402,17 @@ export class WorkflowService {
 		}
 
 		// Transition COMMIT phase complete
-		this.orchestrator.transition({
+		await this.orchestrator.transition({
 			type: 'COMMIT_COMPLETE'
 		});
 
 		// Check if should advance to next subtask
 		const progress = this.orchestrator.getProgress();
 		if (progress.current < progress.total) {
-			this.orchestrator.transition({ type: 'SUBTASK_COMPLETE' });
+			await this.orchestrator.transition({ type: 'SUBTASK_COMPLETE' });
 		} else {
 			// All subtasks complete
-			this.orchestrator.transition({ type: 'ALL_SUBTASKS_COMPLETE' });
+			await this.orchestrator.transition({ type: 'ALL_SUBTASKS_COMPLETE' });
 		}
 
 		return this.getStatus();
@@ -448,7 +448,7 @@ export class WorkflowService {
 		}
 
 		// Transition to COMPLETE
-		this.orchestrator.transition({ type: 'FINALIZE_COMPLETE' });
+		await this.orchestrator.transition({ type: 'FINALIZE_COMPLETE' });
 
 		return this.getStatus();
 	}
@@ -458,7 +458,7 @@ export class WorkflowService {
 	 */
 	async abortWorkflow(): Promise<void> {
 		if (this.orchestrator) {
-			this.orchestrator.transition({ type: 'ABORT' });
+			await this.orchestrator.transition({ type: 'ABORT' });
 		}
 
 		// Delete state file