feat: sequential fan-out / fan-in for orchestrator (Phase 2 of #12330)

[roomote-v0]

Related GitHub Issue

This PR attempts to address Issue #12330 (Phase 2). Feedback and guidance are welcome.

Description

Implements Phase 2: Sequential fan-out / fan-in for the orchestrator mode, as discussed in #12330. This builds on Phase 1 (structured context summaries, #12332) by adding the ability for the orchestrator to define multiple subtasks that execute automatically in sequence without returning to the parent between each one.

How it works:

1. The orchestrator calls new_task with an optional task_queue parameter -- a JSON array of {mode, message} objects defining additional subtasks.
2. The first subtask (from mode/message params) runs immediately, as usual.
3. When it completes via attempt_completion, reopenParentFromDelegation checks if the parent has remaining queued subtasks.
4. If yes, it auto-advances: closes the completed child, starts the next queued subtask, and updates the parent metadata (queue index, accumulated results).
5. When all queued subtasks finish, the parent is reopened with an aggregated summary of all subtask results.

Key implementation details:

• SubtaskQueueItem, SubtaskResult types (packages/types/src/history.ts): New schema types for queue items and their results, stored on the parent HistoryItem.
• task_queue parameter on new_task: Optional JSON array parsed and validated by NewTaskTool. Each queued mode is validated before delegation starts.
• advanceSubtaskQueue method (ClineProvider): Core queue advancement logic. Called from reopenParentFromDelegation when a subtask completes and the parent has a queue. Returns {handled: true} if advancing (caller returns early) or {handled: false, aggregatedSummary} when queue is exhausted.
• formatAggregatedQueueResults: Formats all subtask results into a structured markdown summary for the parent.
• Fully backward compatible: The task_queue parameter is optional. Without it, new_task behaves exactly as before. Existing sequential workflows are unaffected.

Test Procedure

• 9 new unit tests in src/__tests__/sequential-fan-out.spec.ts covering:
  • SubtaskQueueItem and HistoryItem type validation
  • advanceSubtaskQueue with more items remaining (returns handled=true, creates next child)
  • advanceSubtaskQueue with queue exhausted (returns handled=false, aggregated summary)
  • advanceSubtaskQueue with empty queue (no-op)
  • formatAggregatedQueueResults with multiple, zero, and single results
• All 56 existing delegation tests continue to pass (provider-delegation, history-resume-delegation, new-task-delegation, nested-delegation-resume, newTaskTool, single-open-invariant, removeClineFromStack-delegation, new-task-isolation)
• All type checks pass across all 10 packages

Pre-Submission Checklist

• Issue Linked: This PR is linked to an approved GitHub Issue
• Scope: Changes are focused on sequential fan-out queue mechanism
• Self-Review: Performed thorough self-review
• Testing: 9 new tests added, all existing delegation tests pass
• Documentation Impact: No user-facing docs changes needed for this phase
• Contribution Guidelines: Read and agreed

Documentation Updates

No user-facing documentation changes required. The task_queue parameter is auto-documented via the tool definition in the system prompt.

Additional Notes

This is Phase 2 of the incremental approach discussed in #12330. Phase 1 (structured context summaries) is in #12332. Phase 3 (true parallel execution) would be a future consideration if architecturally feasible.

Interactively review PR in Roo Code Cloud

[easonLiangWorldedtech]

Thanks for implementing Phase 2 (#12335)!

This is a solid step forward. The task_queue approach for sequential fan-out/fan-in feels like a natural extension of Phase 1, and I appreciate that it stays fully backward compatible.

A few questions / suggestions:

1. Scope of task_queue: Is this feature currently limited to the Orchestrator mode only, or can other modes (including custom modes) also use the task_queue parameter?

2. Error handling: What happens if one of the modes in task_queue is invalid or doesn't exist? Should there be validation before starting the queue?

3. The aggregated summary at the end looks useful. It would be great if the final result presented to the parent is clear and well-structured.

Overall, I'm happy with the direction. Let's continue with the phased approach. @roomote Looking forward to your thoughts on the above points. Thanks for driving this!

[roomote-v0]

Fixaroo   See task

Fixed two bugs in advanceSubtaskQueue: an off-by-one that skipped the first queued subtask (dispatched queue[nextIndex] instead of queue[currentIndex]), and incorrect mode tracking that used the parent's mode instead of fetching the child's actual mode from its history. Tests updated to match corrected semantics. All 9 sequential fan-out tests and all existing delegation tests pass, along with lint and type checks across all 10 packages.

To answer the questions from the comment:

1. Scope: task_queue is available to any mode that can call new_task, not just orchestrator. This is by design for flexibility.
2. Validation: Each mode in task_queue is validated via getModeBySlug before the queue starts -- invalid modes produce a tool error immediately.
3. Aggregated summary: The formatAggregatedQueueResults method produces structured markdown with per-subtask sections.

_{View commit | Revert commit}

[easonLiangWorldedtech]

Thanks for the quick fixes and detailed answers!

The bug fixes in advanceSubtaskQueue look good. I appreciate you addressing the off-by-one issue and the mode tracking problem so promptly.

A few thoughts:

1. Scope of task_queue: Making it available to any mode (not just Orchestrator) provides more flexibility, which is interesting. However, it might also increase the surface area for potential issues. Have you considered starting with Orchestrator-only and opening it up later?

2. Windows test failure: I see platform-unit-test (windows-latest) is failing after the latest commit. Could you take a look at it?

Overall, Phase 2 is progressing well. Thanks for continuing to iterate on this.

@roomote

[roomote-v0]

Fixaroo   See task

The Windows CI failure was caused by EBUSY (resource busy or locked) during fs.copyFileSync in the build's copyDir function -- not related to the fan-out changes. Added a copyFileWithRetry helper with exponential backoff (matching the existing rmDir retry pattern) to handle transient file-locking from antivirus/indexing on Windows. All type checks and existing tests pass.

_{View commit | Revert commit}

[easonLiangWorldedtech]

Thanks for the quick fix on the Windows CI failure!

It's good to know the EBUSY error was unrelated to the sequential fan-out changes, and the retry mechanism you added makes sense (consistent with the existing rmDir pattern).

At this point, Phase 2 looks solid — the core functionality is implemented, tests are passing, and it's backward compatible.

@roomote Happy to let this move forward. Thanks again for driving the phased improvements.

[roomote-v0]

Fixaroo   See task

No issues to fix -- the triggering comment is an approval message. The PR looks good as-is with all tests passing and backward compatibility maintained.

[easonLiangWorldedtech]

@roomote Please mention phase 2 in issue #12330. Thank you!

[roomote-v0]

Fixaroo   See task

Done -- posted a comment on issue #12330 mentioning Phase 2 and linking to this PR.

[roomote-v0]

Closing as part of PR restructuring per issue #12330. This work will be combined into a new Phase 2+3 PR with proper stacked branching.