fix: preserve user-provided task IDs instead of replacing with auto-generated ones (#542)

When creating tasks in batch with user-provided IDs (e.g., id: "tui-static-gen"),
the ID was only used for dependency resolution then discarded. Tasks were stored
under auto-generated IDs (task-1, task-2). When the AI later tried to complete
by the original ID, it got "Task not found."

Now user-provided IDs are preserved as the actual stored task IDs:
- createTask() accepts optional id field, uses it when provided
- createTasks() no longer maps user IDs to auto-generated ones
- Dependencies reference user IDs directly
- Collision detection for duplicate IDs in both single and batch creation

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

Author: buger

npm/src/agent/tasks/TaskManager.js

@@ -63,7 +63,11 @@ export class TaskManager {
    * @throws {Error} If dependencies are invalid or create a cycle
    */
   createTask(taskData) {
-    const id = this._generateId();
+    const id = taskData.id || this._generateId();
+    // If a user-provided ID collides with an existing task, throw
+    if (taskData.id && this.tasks.has(taskData.id)) {
+      throw new Error(`Task ID "${taskData.id}" already exists. Choose a different ID. Available tasks: ${this._getAvailableTaskIds()}`);
+    }
     const now = this._now();
 
     // Validate dependencies exist
@@ -148,46 +152,42 @@ export class TaskManager {
       }
     }
 
-    // Build a mapping of user-provided IDs to future auto-generated IDs
-    const idMap = new Map();
-    const batchAutoIds = new Set();
-    let nextCounter = this.taskCounter;
+    // Collect all IDs that will exist after this batch (for dependency validation)
+    const batchIds = new Set();
     for (const taskData of tasksData) {
-      nextCounter++;
-      const autoId = `task-${nextCounter}`;
-      batchAutoIds.add(autoId);
       if (taskData.id) {
-        idMap.set(taskData.id, autoId);
+        if (this.tasks.has(taskData.id)) {
+          throw new Error(`Task ID "${taskData.id}" already exists. Choose a different ID. Available tasks: ${this._getAvailableTaskIds()}`);
+        }
+        if (batchIds.has(taskData.id)) {
+          throw new Error(`Duplicate task ID "${taskData.id}" in batch. Each task must have a unique ID.`);
+        }
+        batchIds.add(taskData.id);
       }
     }
 
-    // Resolve dependencies and "after" references, then validate before creating anything
+    // Validate dependencies and "after" references before creating anything
     const resolvedTasksData = tasksData.map(taskData => {
       const resolved = { ...taskData };
-      delete resolved.id; // Don't pass user ID to createTask
 
       if (resolved.dependencies) {
         resolved.dependencies = resolved.dependencies.map(depId => {
-          if (idMap.has(depId)) return idMap.get(depId);
-          // Check if it's already an existing task ID or a batch auto-generated ID
-          if (this.tasks.has(depId) || batchAutoIds.has(depId)) return depId;
-          const batchIds = idMap.size > 0 ? Array.from(idMap.keys()).join(', ') : '(none provided)';
-          throw new Error(`Dependency "${depId}" does not exist. Each task in the batch must have an "id" field, and dependencies must reference those IDs. Current batch IDs: ${batchIds}. Existing tasks: ${this._getAvailableTaskIds()}`);
+          if (batchIds.has(depId) || this.tasks.has(depId)) return depId;
+          const knownIds = batchIds.size > 0 ? Array.from(batchIds).join(', ') : '(none provided)';
+          throw new Error(`Dependency "${depId}" does not exist. Each task in the batch must have an "id" field, and dependencies must reference those IDs. Current batch IDs: ${knownIds}. Existing tasks: ${this._getAvailableTaskIds()}`);
         });
       }
 
       if (resolved.after) {
-        if (idMap.has(resolved.after)) {
-          resolved.after = idMap.get(resolved.after);
-        } else if (!this.tasks.has(resolved.after) && !batchAutoIds.has(resolved.after)) {
-          throw new Error(`Task "${resolved.after}" does not exist. Cannot insert after non-existent task. Available tasks: ${this._getAvailableTaskIds()}${idMap.size > 0 ? `, batch IDs: ${Array.from(idMap.keys()).join(', ')}` : ''}`);
+        if (!batchIds.has(resolved.after) && !this.tasks.has(resolved.after)) {
+          throw new Error(`Task "${resolved.after}" does not exist. Cannot insert after non-existent task. Available tasks: ${this._getAvailableTaskIds()}${batchIds.size > 0 ? `, batch IDs: ${Array.from(batchIds).join(', ')}` : ''}`);
         }
       }
 
       return resolved;
     });
 
-    // All validation passed — create tasks
+    // All validation passed — create tasks (user-provided IDs are preserved by createTask)
     const createdTasks = [];
     for (const taskData of resolvedTasksData) {
       const task = this.createTask(taskData);

npm/tests/unit/task-manager.test.js

@@ -88,27 +88,43 @@ describe('TaskManager', () => {
         { id: 'third', title: 'Task 3', dependencies: ['first', 'second'] }
       ]);
 
-      expect(tasks[1].dependencies).toEqual(['task-1']);
-      expect(tasks[2].dependencies).toEqual(['task-1', 'task-2']);
+      expect(tasks[1].dependencies).toEqual(['first']);
+      expect(tasks[2].dependencies).toEqual(['first', 'second']);
     });
 
-    test('should resolve user-provided IDs to auto-generated IDs in batch dependencies', () => {
+    test('should preserve user-provided IDs in batch creation', () => {
       const tasks = manager.createTasks([
         { id: 'auth', title: 'Authenticate with API' },
         { id: 'list-projects', title: 'List Projects', dependencies: ['auth'] },
         { id: 'list-clusters', title: 'List Clusters', dependencies: ['list-projects'] }
       ]);
 
       expect(tasks).toHaveLength(3);
-      // Dependencies should be remapped to auto-generated IDs
-      expect(tasks[0].id).toBe('task-1');
-      expect(tasks[1].id).toBe('task-2');
-      expect(tasks[1].dependencies).toEqual(['task-1']);
-      expect(tasks[2].id).toBe('task-3');
-      expect(tasks[2].dependencies).toEqual(['task-2']);
+      // User-provided IDs are preserved as-is
+      expect(tasks[0].id).toBe('auth');
+      expect(tasks[1].id).toBe('list-projects');
+      expect(tasks[1].dependencies).toEqual(['auth']);
+      expect(tasks[2].id).toBe('list-clusters');
+      expect(tasks[2].dependencies).toEqual(['list-projects']);
+    });
+
+    test('should allow completing tasks by user-provided ID', () => {
+      manager.createTasks([
+        { id: 'tui-static-gen', title: 'Generate TUI statics' },
+        { id: 'tui-render', title: 'Render TUI', dependencies: ['tui-static-gen'] }
+      ]);
+
+      // Should be able to complete using the user-provided ID
+      const completed = manager.completeTask('tui-static-gen');
+      expect(completed.id).toBe('tui-static-gen');
+      expect(completed.status).toBe('completed');
+
+      // Dependent task should now be unblocked
+      const render = manager.getTask('tui-render');
+      expect(render).toBeTruthy();
     });
 
-    test('should resolve user-provided IDs with multiple dependencies', () => {
+    test('should preserve user-provided IDs with multiple dependencies', () => {
       const tasks = manager.createTasks([
         { id: 'setup', title: 'Setup' },
         { id: 'build', title: 'Build', dependencies: ['setup'] },
@@ -117,10 +133,11 @@ describe('TaskManager', () => {
       ]);
 
       expect(tasks).toHaveLength(4);
-      expect(tasks[3].dependencies).toEqual(['task-2', 'task-3']);
+      expect(tasks[3].id).toBe('deploy');
+      expect(tasks[3].dependencies).toEqual(['build', 'test']);
     });
 
-    test('should resolve user-provided IDs in "after" parameter', () => {
+    test('should preserve user-provided IDs in "after" parameter', () => {
       const tasks = manager.createTasks([
         { id: 'first', title: 'First task' },
         { id: 'third', title: 'Third task' },
@@ -130,7 +147,25 @@ describe('TaskManager', () => {
       expect(tasks).toHaveLength(3);
       const allTasks = manager.listTasks();
       const taskIds = allTasks.map(t => t.id);
-      expect(taskIds).toEqual(['task-1', 'task-3', 'task-2']);
+      expect(taskIds).toEqual(['first', 'second', 'third']);
+    });
+
+    test('should reject duplicate IDs in batch', () => {
+      expect(() => {
+        manager.createTasks([
+          { id: 'dup', title: 'First' },
+          { id: 'dup', title: 'Second' }
+        ]);
+      }).toThrow(/Duplicate task ID "dup"/);
+    });
+
+    test('should reject IDs that collide with existing tasks', () => {
+      manager.createTask({ title: 'Existing' }); // creates task-1
+      expect(() => {
+        manager.createTasks([
+          { id: 'task-1', title: 'Collision' }
+        ]);
+      }).toThrow(/already exists/);
     });
 
     test('should not create any tasks if batch validation fails', () => {