crewly 1.3.31 → 1.4.0

package/dist/backend/backend/src/controllers/task-management/task-management.controller.js

@@ -6,6 +6,8 @@ import { updateAgentHeartbeat } from '../../services/agent/agent-heartbeat.servi
 import { CREWLY_CONSTANTS } from '../../constants.js';
 import { LoggerService } from '../../services/core/logger.service.js';
 import { TaskOutputValidatorService } from '../../services/quality/task-output-validator.service.js';
+import { TracingService } from '../../services/core/tracing.service.js';
+import { TRACING_CONSTANTS } from '../../constants.js';
 import { TASK_OUTPUT_CONSTANTS } from '../../types/task-output.types.js';
 const logger = LoggerService.getInstance().createComponentLogger('TaskManagementController');
 /** Module-level reference to EventBusService for auto-cleanup on task completion */
@@ -67,85 +69,92 @@ export function getEventBusServiceForTaskCleanup() {
  * @param res - Response with success status, created task path, and status
  */
 export async function createTask(req, res) {
-    try {
-        const { projectPath, task, priority = 'medium', sessionName, milestone = 'delegated', outputSchema, } = req.body;
-        if (!projectPath) {
-            res.status(400).json({ success: false, error: 'projectPath is required' });
-            return;
+    return TracingService.getInstance().withSpan(TRACING_CONSTANTS.SPANS.TASK_CREATE, {
+        attributes: {
+            'task.priority': req.body.priority || 'medium',
+            'task.milestone': req.body.milestone || 'delegated',
         }
-        if (!task) {
-            res.status(400).json({ success: false, error: 'task is required' });
-            return;
-        }
-        // Determine initial status folder based on whether an assignee is provided
-        const statusFolder = sessionName ? 'in_progress' : 'open';
-        const tasksDir = join(projectPath, '.crewly', 'tasks', milestone, statusFolder);
-        // Ensure directory exists
-        await ensureDirectoryExists(tasksDir);
-        // Generate sanitized filename from task description
-        const sanitizedName = task
-            .toLowerCase()
-            .replace(/[^a-z0-9]+/g, '_')
-            .replace(/^_|_$/g, '')
-            .substring(0, 80);
-        const timestamp = Date.now();
-        const fileName = `${sanitizedName}_${timestamp}.md`;
-        const taskPath = join(tasksDir, fileName);
-        // Build task markdown content
-        let taskContent = `# ${task}\n\n## Task Information\n- **Priority**: ${priority}\n- **Milestone**: ${milestone}\n- **Created at**: ${new Date().toISOString()}\n- **Status**: ${statusFolder === 'in_progress' ? 'In Progress' : 'Open'}\n`;
-        if (sessionName) {
-            taskContent += `\n## Assignment Information\n- **Assigned to**: ${sessionName}\n- **Assigned at**: ${new Date().toISOString()}\n- **Status**: In Progress\n`;
-        }
-        taskContent += `\n## Task Description\n\n${task}\n`;
-        // Embed output schema if provided
-        if (outputSchema && typeof outputSchema === 'object') {
-            const validator = TaskOutputValidatorService.getInstance();
-            taskContent += validator.generateSchemaMarkdown(outputSchema);
-        }
-        await writeFile(taskPath, taskContent, 'utf-8');
-        // If assigned, track via TaskTrackingService
-        let trackedTaskId;
-        if (sessionName) {
-            try {
-                const projects = await this.storageService.getProjects();
-                const project = projects.find(p => projectPath.startsWith(p.path));
-                if (project) {
-                    const teams = await this.storageService.getTeams();
-                    let teamId = '';
-                    let memberId = '';
-                    for (const team of teams) {
-                        const member = team.members.find(m => m.sessionName === sessionName);
-                        if (member) {
-                            teamId = team.id;
-                            memberId = member.id;
-                            break;
+    }, async (span) => {
+        try {
+            const { projectPath, task, priority = 'medium', sessionName, milestone = 'delegated', outputSchema, } = req.body;
+            if (!projectPath) {
+                res.status(400).json({ success: false, error: 'projectPath is required' });
+                return;
+            }
+            if (!task) {
+                res.status(400).json({ success: false, error: 'task is required' });
+                return;
+            }
+            // Determine initial status folder based on whether an assignee is provided
+            const statusFolder = sessionName ? 'in_progress' : 'open';
+            const tasksDir = join(projectPath, '.crewly', 'tasks', milestone, statusFolder);
+            // Ensure directory exists
+            await ensureDirectoryExists(tasksDir);
+            // Generate sanitized filename from task description
+            const sanitizedName = task
+                .toLowerCase()
+                .replace(/[^a-z0-9]+/g, '_')
+                .replace(/^_|_$/g, '')
+                .substring(0, 80);
+            const timestamp = Date.now();
+            const fileName = `${sanitizedName}_${timestamp}.md`;
+            const taskPath = join(tasksDir, fileName);
+            // Build task markdown content
+            let taskContent = `# ${task}\n\n## Task Information\n- **Priority**: ${priority}\n- **Milestone**: ${milestone}\n- **Created at**: ${new Date().toISOString()}\n- **Status**: ${statusFolder === 'in_progress' ? 'In Progress' : 'Open'}\n`;
+            if (sessionName) {
+                taskContent += `\n## Assignment Information\n- **Assigned to**: ${sessionName}\n- **Assigned at**: ${new Date().toISOString()}\n- **Status**: In Progress\n`;
+            }
+            taskContent += `\n## Task Description\n\n${task}\n`;
+            // Embed output schema if provided
+            if (outputSchema && typeof outputSchema === 'object') {
+                const validator = TaskOutputValidatorService.getInstance();
+                taskContent += validator.generateSchemaMarkdown(outputSchema);
+            }
+            await writeFile(taskPath, taskContent, 'utf-8');
+            // If assigned, track via TaskTrackingService
+            let trackedTaskId;
+            if (sessionName) {
+                try {
+                    const projects = await this.storageService.getProjects();
+                    const project = projects.find(p => projectPath.startsWith(p.path));
+                    if (project) {
+                        const teams = await this.storageService.getTeams();
+                        let teamId = '';
+                        let memberId = '';
+                        for (const team of teams) {
+                            const member = team.members.find(m => m.sessionName === sessionName);
+                            if (member) {
+                                teamId = team.id;
+                                memberId = member.id;
+                                break;
+                            }
+                        }
+                        if (teamId) {
+                            const trackedTask = await this.taskTrackingService.assignTask(project.id, teamId, taskPath, task, 'delegated', memberId, sessionName);
+                            trackedTaskId = trackedTask?.id;
                         }
-                    }
-                    if (teamId) {
-                        const trackedTask = await this.taskTrackingService.assignTask(project.id, teamId, taskPath, task, 'delegated', memberId, sessionName);
-                        trackedTaskId = trackedTask?.id;
                     }
                 }
+                catch (trackingError) {
+                    logger.warn('Failed to track task assignment', { error: trackingError instanceof Error ? trackingError.message : String(trackingError) });
+                    // Non-fatal - the file was still created
+                }
             }
-            catch (trackingError) {
-                logger.warn('Failed to track task assignment', { error: trackingError instanceof Error ? trackingError.message : String(trackingError) });
-                // Non-fatal - the file was still created
-            }
+            res.json({
+                success: true,
+                message: `Task file created: ${fileName}`,
+                taskPath,
+                fileName,
+                status: statusFolder,
+                milestone,
+                taskId: trackedTaskId,
+            });
         }
-        res.json({
-            success: true,
-            message: `Task file created: ${fileName}`,
-            taskPath,
-            fileName,
-            status: statusFolder,
-            milestone,
-            taskId: trackedTaskId,
-        });
-    }
-    catch (error) {
-        logger.error('Error creating task', { error: error instanceof Error ? error.message : String(error) });
-        res.status(500).json({ success: false, error: 'Failed to create task' });
-    }
+        catch (error) {
+            logger.error('Error creating task', { error: error instanceof Error ? error.message : String(error) });
+            res.status(500).json({ success: false, error: 'Failed to create task' });
+        }
+    });
 }
 /**
  * Assigns a task to a team member by moving it from open/ to in_progress/ folder
@@ -154,106 +163,113 @@ export async function createTask(req, res) {
  * @param res - Response with success status and task information
  */
 export async function assignTask(req, res) {
-    try {
-        const { taskPath, sessionName } = req.body;
-        // Update agent heartbeat (proof of life)
-        try {
-            await updateAgentHeartbeat(sessionName, undefined, CREWLY_CONSTANTS.AGENT_STATUSES.ACTIVE);
-        }
-        catch (error) {
-            logger.warn('Failed to update agent heartbeat', { error: error instanceof Error ? error.message : String(error) });
-            // Continue execution - heartbeat failures shouldn't break task assignment
-        }
-        if (!taskPath) {
-            res.status(400).json({ success: false, error: 'taskPath is required' });
-            return;
-        }
-        if (!sessionName) {
-            res.status(400).json({ success: false, error: 'sessionName is required' });
-            return;
+    return TracingService.getInstance().withSpan(TRACING_CONSTANTS.SPANS.TASK_ASSIGN, {
+        attributes: {
+            'task.path': req.body.taskPath || 'unknown',
+            'agent.session': req.body.sessionName || 'unknown',
         }
-        // Verify source task file exists
-        if (!existsSync(taskPath)) {
-            res.status(200).json({
-                success: false,
-                error: 'Task file does not exist at the specified path',
-                details: `No task file found at: ${taskPath}. Make sure the task file exists in the open/ folder.`,
-                taskPath,
-                suggestion: 'Verify the task file path is correct and the file exists'
-            });
-            return;
-        }
-        // Ensure task is in open/ folder
-        if (!taskPath.includes('/open/')) {
-            res.status(200).json({
-                success: false,
-                error: 'Task is not in the correct folder for assignment',
-                details: `Task must be in open/ folder to be assigned. Current path: ${taskPath}`,
-                taskPath,
-                expectedFolder: 'open',
-                currentFolder: taskPath.includes('/in_progress/') ? 'in_progress' : taskPath.includes('/done/') ? 'done' : taskPath.includes('/blocked/') ? 'blocked' : 'unknown'
-            });
-            return;
-        }
-        // Parse task information
-        const taskContent = await readFile(taskPath, 'utf-8');
-        const taskInfo = parseTaskInfo(taskContent, basename(taskPath));
-        // Extract project and team information from task path
-        const pathMatch = taskPath.match(/\/([^/]+)\/\.crewly/);
-        if (!pathMatch) {
-            res.status(400).json({ success: false, error: 'Cannot determine project from task path' });
-            return;
-        }
-        const projectPath = taskPath.substring(0, taskPath.indexOf('.crewly'));
-        // Find project by path
-        const projects = await this.storageService.getProjects();
-        const project = projects.find(p => resolve(p.path) === resolve(projectPath));
-        if (!project) {
-            res.status(404).json({ success: false, error: 'Project not found' });
-            return;
-        }
-        // Find team and member by sessionName
-        const teams = await this.storageService.getTeams();
-        let teamId = '';
-        let memberId = '';
-        for (const team of teams) {
-            const member = team.members.find(m => m.sessionName === sessionName);
-            if (member) {
-                teamId = team.id;
-                memberId = member.id;
-                break;
+    }, async (span) => {
+        try {
+            const { taskPath, sessionName } = req.body;
+            // Update agent heartbeat (proof of life)
+            try {
+                await updateAgentHeartbeat(sessionName, undefined, CREWLY_CONSTANTS.AGENT_STATUSES.ACTIVE);
             }
+            catch (error) {
+                logger.warn('Failed to update agent heartbeat', { error: error instanceof Error ? error.message : String(error) });
+                // Continue execution - heartbeat failures shouldn't break task assignment
+            }
+            if (!taskPath) {
+                res.status(400).json({ success: false, error: 'taskPath is required' });
+                return;
+            }
+            if (!sessionName) {
+                res.status(400).json({ success: false, error: 'sessionName is required' });
+                return;
+            }
+            // Verify source task file exists
+            if (!existsSync(taskPath)) {
+                res.status(200).json({
+                    success: false,
+                    error: 'Task file does not exist at the specified path',
+                    details: `No task file found at: ${taskPath}. Make sure the task file exists in the open/ folder.`,
+                    taskPath,
+                    suggestion: 'Verify the task file path is correct and the file exists'
+                });
+                return;
+            }
+            // Ensure task is in open/ folder
+            if (!taskPath.includes('/open/')) {
+                res.status(200).json({
+                    success: false,
+                    error: 'Task is not in the correct folder for assignment',
+                    details: `Task must be in open/ folder to be assigned. Current path: ${taskPath}`,
+                    taskPath,
+                    expectedFolder: 'open',
+                    currentFolder: taskPath.includes('/in_progress/') ? 'in_progress' : taskPath.includes('/done/') ? 'done' : taskPath.includes('/blocked/') ? 'blocked' : 'unknown'
+                });
+                return;
+            }
+            // Parse task information
+            const taskContent = await readFile(taskPath, 'utf-8');
+            const taskInfo = parseTaskInfo(taskContent, basename(taskPath));
+            // Extract project and team information from task path
+            const pathMatch = taskPath.match(/\/([^/]+)\/\.crewly/);
+            if (!pathMatch) {
+                res.status(400).json({ success: false, error: 'Cannot determine project from task path' });
+                return;
+            }
+            const projectPath = taskPath.substring(0, taskPath.indexOf('.crewly'));
+            // Find project by path
+            const projects = await this.storageService.getProjects();
+            const project = projects.find(p => resolve(p.path) === resolve(projectPath));
+            if (!project) {
+                res.status(404).json({ success: false, error: 'Project not found' });
+                return;
+            }
+            // Find team and member by sessionName
+            const teams = await this.storageService.getTeams();
+            let teamId = '';
+            let memberId = '';
+            for (const team of teams) {
+                const member = team.members.find(m => m.sessionName === sessionName);
+                if (member) {
+                    teamId = team.id;
+                    memberId = member.id;
+                    break;
+                }
+            }
+            if (!teamId) {
+                res.status(404).json({ success: false, error: 'Team member not found for sessionName' });
+                return;
+            }
+            // Create target path in in_progress/ folder
+            const fileName = basename(taskPath);
+            const targetPath = taskPath.replace('/open/', '/in_progress/');
+            const targetDir = dirname(targetPath);
+            // Ensure in_progress directory exists
+            await ensureDirectoryExists(targetDir);
+            // Read, update, and move task file
+            const updatedContent = addTaskAssignmentInfo(taskContent, memberId, sessionName);
+            await writeFile(targetPath, updatedContent, 'utf-8');
+            await unlinkFile(taskPath);
+            // Add to task tracking
+            await this.taskTrackingService.assignTask(project.id, teamId, targetPath, taskInfo.title || taskInfo.fileName, taskInfo.targetRole || 'unknown', memberId, sessionName);
+            res.json({
+                success: true,
+                message: `Task ${fileName} assigned to member ${sessionName}`,
+                originalPath: taskPath,
+                newPath: targetPath,
+                memberId,
+                sessionName,
+                status: 'in_progress',
+            });
         }
-        if (!teamId) {
-            res.status(404).json({ success: false, error: 'Team member not found for sessionName' });
-            return;
+        catch (error) {
+            logger.error('Error assigning task', { error: error instanceof Error ? error.message : String(error) });
+            res.status(500).json({ success: false, error: 'Failed to assign task' });
         }
-        // Create target path in in_progress/ folder
-        const fileName = basename(taskPath);
-        const targetPath = taskPath.replace('/open/', '/in_progress/');
-        const targetDir = dirname(targetPath);
-        // Ensure in_progress directory exists
-        await ensureDirectoryExists(targetDir);
-        // Read, update, and move task file
-        const updatedContent = addTaskAssignmentInfo(taskContent, memberId, sessionName);
-        await writeFile(targetPath, updatedContent, 'utf-8');
-        await unlinkFile(taskPath);
-        // Add to task tracking
-        await this.taskTrackingService.assignTask(project.id, teamId, targetPath, taskInfo.title || taskInfo.fileName, taskInfo.targetRole || 'unknown', memberId, sessionName);
-        res.json({
-            success: true,
-            message: `Task ${fileName} assigned to member ${sessionName}`,
-            originalPath: taskPath,
-            newPath: targetPath,
-            memberId,
-            sessionName,
-            status: 'in_progress',
-        });
-    }
-    catch (error) {
-        logger.error('Error assigning task', { error: error instanceof Error ? error.message : String(error) });
-        res.status(500).json({ success: false, error: 'Failed to assign task' });
-    }
+    });
 }
 /**
  * Completes a task by moving it from in_progress/ to done/ folder
@@ -262,203 +278,222 @@ export async function assignTask(req, res) {
  * @param res - Response with success status and completion information
  */
 export async function completeTask(req, res) {
-    try {
-        const { taskPath, sessionName, output } = req.body;
-        // Update agent heartbeat (proof of life)
-        try {
-            await updateAgentHeartbeat(sessionName, undefined, CREWLY_CONSTANTS.AGENT_STATUSES.ACTIVE);
-        }
-        catch (error) {
-            logger.warn('Failed to update agent heartbeat', { error: error instanceof Error ? error.message : String(error) });
-            // Continue execution - heartbeat failures shouldn't break task completion
+    return TracingService.getInstance().withSpan(TRACING_CONSTANTS.SPANS.TASK_COMPLETE, {
+        attributes: {
+            'task.path': req.body.taskPath || 'unknown',
+            'agent.session': req.body.sessionName || 'unknown',
         }
-        if (!taskPath) {
-            res.status(400).json({ success: false, error: 'taskPath is required' });
-            return;
-        }
-        // Verify source task file exists
-        if (!existsSync(taskPath)) {
-            res.status(200).json({
-                success: false,
-                error: 'Task file does not exist at the specified path',
-                details: `No task file found at: ${taskPath}. Make sure the task has been properly assigned and is in the in_progress folder.`,
-                taskPath,
-                suggestion: 'Check if the task file exists and use accept_task first to move it from open/ to in_progress/'
-            });
-            return;
-        }
-        // Ensure task is in in_progress/ folder
-        if (!taskPath.includes('/in_progress/')) {
-            res.status(200).json({
-                success: false,
-                error: 'Task is not in the correct folder for completion',
-                details: `Task must be in in_progress/ folder to be completed. Current path: ${taskPath}. Use accept_task first to move the task from open/ to in_progress/.`,
-                taskPath,
-                expectedFolder: 'in_progress',
-                currentFolder: taskPath.includes('/open/') ? 'open' : taskPath.includes('/done/') ? 'done' : taskPath.includes('/blocked/') ? 'blocked' : 'unknown',
-                action: 'Use accept_task tool first to assign the task'
-            });
-            return;
-        }
-        // Read task content to check for output schema
-        const taskContent = await readFile(taskPath, 'utf-8');
-        const validator = TaskOutputValidatorService.getInstance();
-        const schema = validator.extractSchemaFromMarkdown(taskContent);
-        // If task has an output schema, validate the output
-        if (schema) {
-            if (!output || typeof output !== 'object') {
+    }, async (span) => {
+        try {
+            const { taskPath, sessionName, output, qualityScore } = req.body;
+            // Update agent heartbeat (proof of life)
+            try {
+                await updateAgentHeartbeat(sessionName, undefined, CREWLY_CONSTANTS.AGENT_STATUSES.ACTIVE);
+            }
+            catch (error) {
+                logger.warn('Failed to update agent heartbeat', { error: error instanceof Error ? error.message : String(error) });
+                // Continue execution - heartbeat failures shouldn't break task completion
+            }
+            if (!taskPath) {
+                res.status(400).json({ success: false, error: 'taskPath is required' });
+                return;
+            }
+            // Verify source task file exists
+            if (!existsSync(taskPath)) {
                 res.status(200).json({
                     success: false,
-                    error: 'Task requires structured output but none was provided',
-                    details: 'This task has an output schema. Provide an "output" object matching the schema.',
+                    error: 'Task file does not exist at the specified path',
+                    details: `No task file found at: ${taskPath}. Make sure the task has been properly assigned and is in the in_progress folder.`,
                     taskPath,
+                    suggestion: 'Check if the task file exists and use accept_task first to move it from open/ to in_progress/'
                 });
                 return;
             }
-            // Check output size
-            const sizeCheck = validator.validateOutputSize(output);
-            if (!sizeCheck.valid) {
+            // Ensure task is in in_progress/ folder
+            if (!taskPath.includes('/in_progress/')) {
                 res.status(200).json({
                     success: false,
-                    error: 'Output size exceeds maximum',
-                    details: sizeCheck.error,
+                    error: 'Task is not in the correct folder for completion',
+                    details: `Task must be in in_progress/ folder to be completed. Current path: ${taskPath}. Use accept_task first to move the task from open/ to in_progress/.`,
                     taskPath,
+                    expectedFolder: 'in_progress',
+                    currentFolder: taskPath.includes('/open/') ? 'open' : taskPath.includes('/done/') ? 'done' : taskPath.includes('/blocked/') ? 'blocked' : 'unknown',
+                    action: 'Use accept_task tool first to assign the task'
                 });
                 return;
             }
-            // Validate output against schema
-            const validationResult = validator.validate(output, schema);
-            if (!validationResult.valid) {
-                // Check retry info
-                const existingRetryInfo = validator.extractRetryInfoFromMarkdown(taskContent);
-                const retryCount = existingRetryInfo ? existingRetryInfo.retryCount + 1 : 1;
-                const maxRetries = TASK_OUTPUT_CONSTANTS.MAX_RETRIES;
-                if (retryCount > maxRetries) {
-                    // Max retries exceeded - move to blocked
-                    const blockedPath = taskPath.replace('/in_progress/', '/blocked/');
-                    const blockedDir = dirname(blockedPath);
-                    await ensureDirectoryExists(blockedDir);
-                    const failureInfo = `\n\n${TASK_OUTPUT_CONSTANTS.SECTION_HEADERS.VALIDATION_FAILURE}\n- **Status**: Blocked (max validation retries exceeded)\n- **Retry count**: ${retryCount}/${maxRetries}\n- **Errors**: ${validationResult.errors.join('; ')}\n- **Blocked at**: ${new Date().toISOString()}\n`;
-                    const blockedContent = taskContent + failureInfo;
-                    await writeFile(blockedPath, blockedContent, 'utf-8');
-                    await unlinkFile(taskPath);
+            // Read task content to check for output schema
+            const taskContent = await readFile(taskPath, 'utf-8');
+            const validator = TaskOutputValidatorService.getInstance();
+            const schema = validator.extractSchemaFromMarkdown(taskContent);
+            // If task has an output schema, validate the output
+            if (schema) {
+                if (!output || typeof output !== 'object') {
+                    res.status(200).json({
+                        success: false,
+                        error: 'Task requires structured output but none was provided',
+                        details: 'This task has an output schema. Provide an "output" object matching the schema.',
+                        taskPath,
+                    });
+                    return;
+                }
+                // Check output size
+                const sizeCheck = validator.validateOutputSize(output);
+                if (!sizeCheck.valid) {
+                    res.status(200).json({
+                        success: false,
+                        error: 'Output size exceeds maximum',
+                        details: sizeCheck.error,
+                        taskPath,
+                    });
+                    return;
+                }
+                // Validate output against schema
+                const validationResult = validator.validate(output, schema);
+                if (!validationResult.valid) {
+                    // Check retry info
+                    const existingRetryInfo = validator.extractRetryInfoFromMarkdown(taskContent);
+                    const retryCount = existingRetryInfo ? existingRetryInfo.retryCount + 1 : 1;
+                    const maxRetries = TASK_OUTPUT_CONSTANTS.MAX_RETRIES;
+                    if (retryCount > maxRetries) {
+                        // Max retries exceeded - move to blocked
+                        const blockedPath = taskPath.replace('/in_progress/', '/blocked/');
+                        const blockedDir = dirname(blockedPath);
+                        await ensureDirectoryExists(blockedDir);
+                        const failureInfo = `\n\n${TASK_OUTPUT_CONSTANTS.SECTION_HEADERS.VALIDATION_FAILURE}\n- **Status**: Blocked (max validation retries exceeded)\n- **Retry count**: ${retryCount}/${maxRetries}\n- **Errors**: ${validationResult.errors.join('; ')}\n- **Blocked at**: ${new Date().toISOString()}\n`;
+                        const blockedContent = taskContent + failureInfo;
+                        await writeFile(blockedPath, blockedContent, 'utf-8');
+                        await unlinkFile(taskPath);
+                        res.status(200).json({
+                            success: false,
+                            validationFailed: true,
+                            maxRetriesExceeded: true,
+                            errors: validationResult.errors,
+                            retryCount,
+                            maxRetries,
+                            message: `Task moved to blocked/ after ${maxRetries} failed validation attempts`,
+                            taskPath: blockedPath,
+                        });
+                        return;
+                    }
+                    // Retries remaining - update retry info in task file
+                    const retryInfo = {
+                        retryCount,
+                        maxRetries,
+                        lastErrors: validationResult.errors,
+                        lastAttemptAt: new Date().toISOString(),
+                    };
+                    // Remove existing retry info section if present, then append new one
+                    const retryHeader = TASK_OUTPUT_CONSTANTS.SECTION_HEADERS.RETRY_INFO;
+                    let updatedTaskContent = taskContent;
+                    const retryHeaderIdx = updatedTaskContent.indexOf(retryHeader);
+                    if (retryHeaderIdx !== -1) {
+                        // Find the end of the retry section (next ## header or end of file)
+                        const afterRetry = updatedTaskContent.substring(retryHeaderIdx + retryHeader.length);
+                        const nextSectionMatch = afterRetry.match(/\n## /);
+                        if (nextSectionMatch && nextSectionMatch.index !== undefined) {
+                            updatedTaskContent = updatedTaskContent.substring(0, retryHeaderIdx) +
+                                updatedTaskContent.substring(retryHeaderIdx + retryHeader.length + nextSectionMatch.index);
+                        }
+                        else {
+                            updatedTaskContent = updatedTaskContent.substring(0, retryHeaderIdx);
+                        }
+                    }
+                    updatedTaskContent += validator.generateRetryMarkdown(retryInfo);
+                    await writeFile(taskPath, updatedTaskContent, 'utf-8');
                     res.status(200).json({
                         success: false,
                         validationFailed: true,
-                        maxRetriesExceeded: true,
                         errors: validationResult.errors,
                         retryCount,
                         maxRetries,
-                        message: `Task moved to blocked/ after ${maxRetries} failed validation attempts`,
-                        taskPath: blockedPath,
+                        message: `Output validation failed. ${maxRetries - retryCount} retries remaining.`,
+                        taskPath,
                     });
                     return;
                 }
-                // Retries remaining - update retry info in task file
-                const retryInfo = {
-                    retryCount,
-                    maxRetries,
-                    lastErrors: validationResult.errors,
-                    lastAttemptAt: new Date().toISOString(),
+                // Validation passed - store output file alongside the done task
+                const doneTargetPath = taskPath.replace('/in_progress/', '/done/');
+                const outputFilePath = doneTargetPath.replace(/\.md$/, TASK_OUTPUT_CONSTANTS.OUTPUT_FILE_EXTENSION);
+                const doneDir = dirname(doneTargetPath);
+                await ensureDirectoryExists(doneDir);
+                const outputData = {
+                    output,
+                    producedAt: new Date().toISOString(),
+                    sessionName: sessionName || 'unknown',
                 };
-                // Remove existing retry info section if present, then append new one
-                const retryHeader = TASK_OUTPUT_CONSTANTS.SECTION_HEADERS.RETRY_INFO;
-                let updatedTaskContent = taskContent;
-                const retryHeaderIdx = updatedTaskContent.indexOf(retryHeader);
-                if (retryHeaderIdx !== -1) {
-                    // Find the end of the retry section (next ## header or end of file)
-                    const afterRetry = updatedTaskContent.substring(retryHeaderIdx + retryHeader.length);
-                    const nextSectionMatch = afterRetry.match(/\n## /);
-                    if (nextSectionMatch && nextSectionMatch.index !== undefined) {
-                        updatedTaskContent = updatedTaskContent.substring(0, retryHeaderIdx) +
-                            updatedTaskContent.substring(retryHeaderIdx + retryHeader.length + nextSectionMatch.index);
-                    }
-                    else {
-                        updatedTaskContent = updatedTaskContent.substring(0, retryHeaderIdx);
+                await writeFile(outputFilePath, JSON.stringify(outputData, null, 2), 'utf-8');
+                // Move task to done
+                const updatedContent = addTaskCompletionInfo(taskContent);
+                await writeFile(doneTargetPath, updatedContent, 'utf-8');
+                await unlinkFile(taskPath);
+                // Remove from task tracking and clean up monitoring
+                const allTasksWithSchema = await this.taskTrackingService.getAllInProgressTasks();
+                const taskToRemoveWithSchema = allTasksWithSchema.find(t => t.taskFilePath === taskPath);
+                let cleanupResultSchema = { cancelledSchedules: 0, unsubscribedEvents: 0 };
+                if (taskToRemoveWithSchema) {
+                    // #174: Store quality score on task before completing
+                    if (typeof qualityScore === 'number' && qualityScore >= 0 && qualityScore <= 100) {
+                        taskToRemoveWithSchema.qualityScore = qualityScore;
+                        taskToRemoveWithSchema.scoredAt = new Date().toISOString();
+                        taskToRemoveWithSchema.scoredBy = sessionName;
                     }
+                    publishTaskCompletedEvent(taskToRemoveWithSchema, sessionName);
+                    cleanupResultSchema = await cleanupTaskMonitoring(this, taskToRemoveWithSchema);
+                    await this.taskTrackingService.removeTask(taskToRemoveWithSchema.id);
                 }
-                updatedTaskContent += validator.generateRetryMarkdown(retryInfo);
-                await writeFile(taskPath, updatedTaskContent, 'utf-8');
-                res.status(200).json({
-                    success: false,
-                    validationFailed: true,
-                    errors: validationResult.errors,
-                    retryCount,
-                    maxRetries,
-                    message: `Output validation failed. ${maxRetries - retryCount} retries remaining.`,
-                    taskPath,
+                res.json({
+                    success: true,
+                    message: `Task ${basename(taskPath)} marked as completed with validated output`,
+                    originalPath: taskPath,
+                    newPath: doneTargetPath,
+                    outputPath: outputFilePath,
+                    status: 'done',
+                    completedAt: new Date().toISOString(),
+                    monitoringCleanup: cleanupResultSchema,
                 });
                 return;
             }
-            // Validation passed - store output file alongside the done task
-            const doneTargetPath = taskPath.replace('/in_progress/', '/done/');
-            const outputFilePath = doneTargetPath.replace(/\.md$/, TASK_OUTPUT_CONSTANTS.OUTPUT_FILE_EXTENSION);
-            const doneDir = dirname(doneTargetPath);
-            await ensureDirectoryExists(doneDir);
-            const outputData = {
-                output,
-                producedAt: new Date().toISOString(),
-                sessionName: sessionName || 'unknown',
-            };
-            await writeFile(outputFilePath, JSON.stringify(outputData, null, 2), 'utf-8');
-            // Move task to done
+            // No schema - original behavior (backward compatible)
+            const fileName = basename(taskPath);
+            const targetPath = taskPath.replace('/in_progress/', '/done/');
+            const targetDir = dirname(targetPath);
+            // Ensure done directory exists
+            await ensureDirectoryExists(targetDir);
+            // Read, update, and move task file
             const updatedContent = addTaskCompletionInfo(taskContent);
-            await writeFile(doneTargetPath, updatedContent, 'utf-8');
+            await writeFile(targetPath, updatedContent, 'utf-8');
             await unlinkFile(taskPath);
             // Remove from task tracking and clean up monitoring
-            const allTasksWithSchema = await this.taskTrackingService.getAllInProgressTasks();
-            const taskToRemoveWithSchema = allTasksWithSchema.find(t => t.taskFilePath === taskPath);
-            let cleanupResultSchema = { cancelledSchedules: 0, unsubscribedEvents: 0 };
-            if (taskToRemoveWithSchema) {
-                publishTaskCompletedEvent(taskToRemoveWithSchema, sessionName);
-                cleanupResultSchema = await cleanupTaskMonitoring(this, taskToRemoveWithSchema);
-                await this.taskTrackingService.removeTask(taskToRemoveWithSchema.id);
+            const allTasks = await this.taskTrackingService.getAllInProgressTasks();
+            const taskToRemove = allTasks.find(t => t.taskFilePath === taskPath);
+            let cleanupResult = { cancelledSchedules: 0, unsubscribedEvents: 0 };
+            if (taskToRemove) {
+                // #174: Store quality score on task before completing
+                if (typeof qualityScore === 'number' && qualityScore >= 0 && qualityScore <= 100) {
+                    taskToRemove.qualityScore = qualityScore;
+                    taskToRemove.scoredAt = new Date().toISOString();
+                    taskToRemove.scoredBy = sessionName;
+                }
+                publishTaskCompletedEvent(taskToRemove, sessionName);
+                cleanupResult = await cleanupTaskMonitoring(this, taskToRemove);
+                await this.taskTrackingService.removeTask(taskToRemove.id);
             }
             res.json({
                 success: true,
-                message: `Task ${basename(taskPath)} marked as completed with validated output`,
+                message: `Task ${fileName} marked as completed`,
                 originalPath: taskPath,
-                newPath: doneTargetPath,
-                outputPath: outputFilePath,
+                newPath: targetPath,
                 status: 'done',
                 completedAt: new Date().toISOString(),
-                monitoringCleanup: cleanupResultSchema,
+                monitoringCleanup: cleanupResult,
             });
-            return;
         }
-        // No schema - original behavior (backward compatible)
-        const fileName = basename(taskPath);
-        const targetPath = taskPath.replace('/in_progress/', '/done/');
-        const targetDir = dirname(targetPath);
-        // Ensure done directory exists
-        await ensureDirectoryExists(targetDir);
-        // Read, update, and move task file
-        const updatedContent = addTaskCompletionInfo(taskContent);
-        await writeFile(targetPath, updatedContent, 'utf-8');
-        await unlinkFile(taskPath);
-        // Remove from task tracking and clean up monitoring
-        const allTasks = await this.taskTrackingService.getAllInProgressTasks();
-        const taskToRemove = allTasks.find(t => t.taskFilePath === taskPath);
-        let cleanupResult = { cancelledSchedules: 0, unsubscribedEvents: 0 };
-        if (taskToRemove) {
-            publishTaskCompletedEvent(taskToRemove, sessionName);
-            cleanupResult = await cleanupTaskMonitoring(this, taskToRemove);
-            await this.taskTrackingService.removeTask(taskToRemove.id);
+        catch (error) {
+            logger.error('Error completing task', { error: error instanceof Error ? error.message : String(error) });
+            res.status(500).json({ success: false, error: 'Failed to complete task' });
         }
-        res.json({
-            success: true,
-            message: `Task ${fileName} marked as completed`,
-            originalPath: taskPath,
-            newPath: targetPath,
-            status: 'done',
-            completedAt: new Date().toISOString(),
-            monitoringCleanup: cleanupResult,
-        });
-    }
-    catch (error) {
-        logger.error('Error completing task', { error: error instanceof Error ? error.message : String(error) });
-        res.status(500).json({ success: false, error: 'Failed to complete task' });
-    }
+    });
 }
 /**
  * Blocks a task by moving it from in_progress/ to blocked/ folder
@@ -1456,4 +1491,241 @@ export async function completeTasksBySession(req, res) {
         res.status(500).json({ success: false, error: 'Failed to complete tasks by session' });
     }
 }
+/**
+ * GET /task-management/tasks
+ *
+ * List task files for a project, optionally filtered by status.
+ * Returns task filenames and paths grouped by milestone.
+ *
+ * @param req - Request with query: { projectPath, status? }
+ * @param res - Response with { success, tasks }
+ */
+/**
+ * Detect and optionally clean up orphan tasks — tasks stuck in progress
+ * assigned to agents that no longer exist or have been inactive too long.
+ *
+ * POST /api/task-management/cleanup
+ * Body:
+ *   - action: 'detect' (default, dry run) | 'cancel' | 'reopen'
+ *   - staleThresholdHours: number (default 24)
+ *   - taskIds: string[] (optional, specific tasks to clean; if omitted, cleans all detected orphans)
+ *
+ * @param req - Request with cleanup parameters
+ * @param res - Response with orphan detection/cleanup report
+ * @see https://github.com/stevehuang0115/crewly/issues/168
+ */
+export async function cleanupOrphanTasks(req, res) {
+    try {
+        const { action = 'detect', staleThresholdHours = 24, taskIds, } = req.body;
+        const staleThresholdMs = staleThresholdHours * 60 * 60 * 1000;
+        const getTeamStatus = async () => {
+            return await this.storageService.getTeams();
+        };
+        // Step 1: Detect orphan tasks
+        const orphans = await this.taskTrackingService.detectOrphanTasks(getTeamStatus, staleThresholdMs);
+        if (action === 'detect') {
+            res.json({
+                success: true,
+                message: `Found ${orphans.length} orphan task(s)`,
+                data: {
+                    orphanCount: orphans.length,
+                    orphans: orphans.map(t => ({
+                        id: t.id,
+                        taskName: t.taskName,
+                        assignedSessionName: t.assignedSessionName,
+                        assignedTeamMemberId: t.assignedTeamMemberId,
+                        status: t.status,
+                        assignedAt: t.assignedAt,
+                        staleSinceHours: Math.round(t.staleSinceMs / (60 * 60 * 1000) * 10) / 10,
+                        taskFilePath: t.taskFilePath,
+                    })),
+                },
+            });
+            return;
+        }
+        // Step 2: Clean up
+        const idsToClean = taskIds || orphans.map(t => t.id);
+        if (idsToClean.length === 0) {
+            res.json({ success: true, message: 'No orphan tasks to clean up', data: { cleaned: 0 } });
+            return;
+        }
+        const cleanupAction = action === 'reopen' ? 'reopen' : 'cancel';
+        const report = await this.taskTrackingService.cleanupOrphanTasks(idsToClean, cleanupAction);
+        logger.info('Orphan task cleanup completed', {
+            action: cleanupAction,
+            cleaned: report.cleaned,
+            errors: report.errors.length,
+        });
+        res.json({
+            success: true,
+            message: `Cleaned ${report.cleaned} orphan task(s) (action: ${cleanupAction})`,
+            data: {
+                cleaned: report.cleaned,
+                errors: report.errors,
+                totalOrphansDetected: orphans.length,
+            },
+        });
+    }
+    catch (error) {
+        logger.error('Orphan task cleanup failed', { error: error instanceof Error ? error.message : String(error) });
+        res.status(500).json({
+            success: false,
+            error: 'Failed to clean up orphan tasks',
+            details: error instanceof Error ? error.message : String(error),
+        });
+    }
+}
+export async function listTasks(req, res) {
+    try {
+        const projectPath = req.query.projectPath;
+        const statusFilter = req.query.status;
+        if (!projectPath) {
+            res.status(400).json({ success: false, error: 'projectPath query parameter is required' });
+            return;
+        }
+        // Validate status filter against known values to prevent path traversal
+        const VALID_STATUSES = ['open', 'in_progress', 'blocked', 'done'];
+        if (statusFilter && !VALID_STATUSES.includes(statusFilter)) {
+            res.status(400).json({ success: false, error: `status must be one of: ${VALID_STATUSES.join(', ')}` });
+            return;
+        }
+        // Resolve and validate project path to prevent directory traversal
+        const resolvedPath = resolve(projectPath);
+        const tasksBasePath = join(resolvedPath, '.crewly', 'tasks');
+        if (!existsSync(tasksBasePath)) {
+            res.json({ success: true, tasks: [] });
+            return;
+        }
+        const tasks = [];
+        const milestones = await readdir(tasksBasePath);
+        for (const milestone of milestones) {
+            const milestonePath = join(tasksBasePath, milestone);
+            const milestoneStat = await stat(milestonePath).catch(() => null);
+            if (!milestoneStat?.isDirectory())
+                continue;
+            const statusDirs = statusFilter ? [statusFilter] : [...VALID_STATUSES];
+            for (const status of statusDirs) {
+                const statusPath = join(milestonePath, status);
+                if (!existsSync(statusPath))
+                    continue;
+                const files = await readdir(statusPath);
+                for (const file of files) {
+                    if (file.endsWith('.md')) {
+                        tasks.push({
+                            name: file.replace('.md', ''),
+                            path: join(statusPath, file),
+                            milestone,
+                            status,
+                        });
+                    }
+                }
+            }
+        }
+        res.json({ success: true, tasks });
+    }
+    catch (error) {
+        logger.error('Error listing tasks', { error: error instanceof Error ? error.message : String(error) });
+        res.status(500).json({ success: false, error: 'Failed to list tasks' });
+    }
+}
+/**
+ * Score a completed task's quality (#174).
+ * Called by the auditor's score-task skill after task:completed events.
+ * Updates the task's qualityScore in the tracking data.
+ *
+ * @param req - Request containing taskId, qualityScore, and optional scoredBy
+ * @param res - Response with success status
+ */
+export async function scoreTask(req, res) {
+    try {
+        const { taskId, qualityScore, scoredBy } = req.body;
+        if (!taskId) {
+            res.status(400).json({ success: false, error: 'taskId is required' });
+            return;
+        }
+        if (typeof qualityScore !== 'number' || qualityScore < 0 || qualityScore > 100) {
+            res.status(400).json({ success: false, error: 'qualityScore must be a number between 0 and 100' });
+            return;
+        }
+        // Load task data directly for in-place update
+        const taskData = await this.taskTrackingService.loadTaskData();
+        const task = taskData.tasks.find(t => t.id === taskId);
+        if (task) {
+            // Task still in tracking — update in place and persist
+            task.qualityScore = qualityScore;
+            task.scoredAt = new Date().toISOString();
+            task.scoredBy = scoredBy || 'auditor';
+            await this.taskTrackingService.saveTaskData(taskData);
+            logger.info('Task scored', { taskId, qualityScore, scoredBy: scoredBy || 'auditor' });
+            res.json({ success: true, message: 'Task scored successfully', taskId, qualityScore });
+        }
+        else {
+            // Task already removed from tracking — score acknowledged
+            logger.warn('Task not found in tracking (may already be completed)', { taskId });
+            res.json({ success: true, message: 'Score acknowledged but task already completed', taskId, qualityScore });
+        }
+    }
+    catch (error) {
+        logger.error('Error scoring task', { error: error instanceof Error ? error.message : String(error) });
+        res.status(500).json({ success: false, error: 'Failed to score task' });
+    }
+}
+/**
+ * Record a task handoff from one agent to another (F12).
+ *
+ * POST /api/task-management/handoff
+ * Body: { from, to, taskPath?, reason, progress?, projectPath? }
+ *
+ * Updates the task tracking data to reflect the handoff and logs the event.
+ *
+ * @param req - Request with handoff parameters
+ * @param res - Response with handoff record
+ */
+export async function recordHandoff(req, res) {
+    try {
+        const { from, to, taskPath, reason, progress, projectPath } = req.body;
+        if (!from || !to || !reason) {
+            res.status(400).json({ success: false, error: 'from, to, and reason are required' });
+            return;
+        }
+        // Find the task being handed off (by assignedSessionName)
+        const tasks = await this.taskTrackingService.getTasksBySessionName(from);
+        const activeTask = tasks.find(t => t.status === 'assigned' || t.status === 'active' || t.status === 'working');
+        if (activeTask) {
+            // Update task assignment to new agent
+            const data = await this.taskTrackingService.loadTaskData();
+            const task = data.tasks.find(t => t.id === activeTask.id);
+            if (task) {
+                task.assignedSessionName = to;
+                task.status = 'assigned';
+                task.statusHistory = task.statusHistory || [];
+                task.statusHistory.push({
+                    timestamp: new Date().toISOString(),
+                    fromStatus: activeTask.status,
+                    toStatus: 'assigned',
+                    message: `Handed off from ${from} to ${to}: ${reason}`,
+                    reportedBy: from,
+                });
+                await this.taskTrackingService.saveTaskData(data);
+            }
+        }
+        logger.info('Task handoff recorded', { from, to, reason, taskId: activeTask?.id });
+        res.json({
+            success: true,
+            handoff: {
+                from,
+                to,
+                reason,
+                taskId: activeTask?.id || null,
+                taskPath: taskPath || null,
+                progress: progress || null,
+                timestamp: new Date().toISOString(),
+            },
+        });
+    }
+    catch (error) {
+        logger.error('Error recording handoff', { error: error instanceof Error ? error.message : String(error) });
+        res.status(500).json({ success: false, error: 'Failed to record handoff' });
+    }
+}
 //# sourceMappingURL=task-management.controller.js.map