Parallel Dispatcher and Concurrency

Relevant source files

The following files were used as context for generating this wiki page:

• src/parallel/dispatcher/parallel-dispatcher.ts
• src/parallel/dependency-graph.ts
• src/parallel/file-locks.ts
• src/agents/architect.ts
• src/hooks/system-enhancer.ts
• src/tools/declare-scope.ts

The Parallel Dispatcher and Concurrency system in opencode-swarm is designed to enable the simultaneous execution of multiple agent tasks while maintaining strict safety guarantees. Its primary purpose is to scale implementation capacity by allowing up to four coders to run in parallel, provided their tasks do not have overlapping file dependencies or logical blockages. This system is crucial for performance optimization in complex projects where linear task execution would otherwise create significant bottlenecks.

The architecture relies on three core pillars: dependency resolution, file-level locking, and a centralized dispatcher. By analyzing task dependencies defined in the project plan and enforcing mutual exclusion on files, the system prevents race conditions and state corruption that could occur if multiple agents attempted to modify the same source code simultaneously.

Architecture and Core Logic

The concurrency system is managed by the ParallelDispatcher, which orchestrates task execution based on a combination of user-defined constraints and automated safety checks. It interfaces with the DependencyGraph to determine the order of operations and FileLocks to manage resource contention.

Dispatcher Workflow

The dispatcher follows a strict lifecycle for each task batch:

1. Configuration Check: Determines if parallelization is enabled and what the max_concurrent_tasks limit is (ranging from 1 to 4).
2. Dependency Analysis: Queries the DependencyGraph to identify tasks that are "ready" (all upstream dependencies are met).
3. Resource Allocation: Attempts to acquire FileLocks for the files declared in the task's scope.
4. Agent Dispatch: Launches subagents (typically @coder agents) for each viable task.
5. Completion and Release: Updates task status upon completion and releases associated file locks to unblock downstream tasks.

The diagram shows the iterative loop the Parallel Dispatcher uses to move through a phase's task list while respecting concurrency limits.
Sources: src/parallel/dispatcher/parallel-dispatcher.ts, src/agents/architect.ts:1016-1033

Dependency Management

The DependencyGraph is responsible for maintaining the topological order of tasks within a phase. It ensures that no task is dispatched before its prerequisites are successfully completed.

Key Logic and Invariants

• Prerequisite Validation: A task is only considered a candidate for execution if its depends array contains only IDs of tasks marked as completed.
• Granularity Enforcement: The system discourages large, monolithic tasks that touch many files, as these create broad dependency blockages that hinder parallelization.
• Blockage Propagation: If a task is marked [BLOCKED], all downstream tasks that depend on it are automatically ineligible for dispatch.

Sources: src/parallel/dependency-graph.ts, src/agents/architect.ts:983-987

File-Level Locking and Scope Discipline

Concurrency safety is enforced through a strict locking mechanism that prevents multiple agents from modifying the same files at the same time. This is integrated with the "Scope Discipline" protocol.

Scope Declaration

Before any coder is dispatched, the Architect must invoke the declare_scope tool. This tool sets the definitive list of files a specific task ID is allowed to touch. The Parallel Dispatcher uses this declared scope to request file locks.

Lock Implementation

• Mutual Exclusion: A file can only be associated with one active task. If task A and task B both require src/utils.ts, they cannot run in parallel.
• Directory Containment: Locks can be applied to entire directories if the scope is broad (e.g., during a refactor), effectively blocking any other task from touching files within that directory.
• Symlink Protection: The declare_scope tool performs lstat checks to reject paths that are symlinks, preventing writes from escaping the intended project root and corrupting external state.

Field	Type	Description
taskId	string	The N.M identifier for the task (e.g., "1.1").
files	string[]	Array of relative paths to be locked for this task.
whitelist	string[]	Additional paths allowed but not primary to the task.

Sources: src/tools/declare-scope.ts:14-41, src/parallel/file-locks.ts, src/agents/architect.ts:66-83

Configuration and User Controls

The concurrency behavior is configurable via the ## Pending Parallelization Config section in .swarm/context.md. Users can tune the throughput of the swarm based on their hardware and model rate limits.

Parallelization Options

Users are prompted to configure these settings during the PLAN mode or via explicit commands:

• Max Concurrent Tasks: Limits the number of simultaneous @coder agents (1–4).
• Commit Frequency: Determines if the system should commit changes after every task completion or only at the phase boundary. Per-task commits are recommended for large parallel runs to provide granular checkpoints.

{
  "parallelization_enabled": true,
  "max_concurrent_tasks": 3,
  "commit_after_each_completed_task": true,
  "recorded_at": "2023-10-27T10:00:00Z"
}

Example configuration for parallel execution.
Sources: src/agents/architect.ts:1016-1033, src/hooks/system-enhancer.ts:474-485

Safety Constraints and Anti-Patterns

To ensure parallel execution does not lead to regressions, the system enforces several hardening rules:

1. No Batching: Each coder task must be atomic. Phrases like "and", "also", or "additionally" in a task description indicate batching, which the Architect is instructed to split into separate parallelizable tasks.
2. QA Gate Integration: Every parallel task must independently pass the full Stage A (automated tools) and Stage B (agent review) QA gates. Parallel execution does not exempt tasks from linting, testing, or review.
3. Human-Only Overrides: Destructive state operations or releasing runtime safety gates (like reset or acknowledge-spec-drift) are restricted to human users and cannot be invoked by parallel agents or the dispatcher itself.

Sources: src/agents/architect.ts:68-100, src/agents/architect.ts:1037-1049

Conclusion

The Parallel Dispatcher and Concurrency system provides a robust framework for multi-agent collaboration in opencode-swarm. By combining topological dependency sorting with granular file locks and strict scope enforcement, it allows the project to benefit from parallel task execution without sacrificing code integrity. The integration of user-configurable limits and mandatory QA gates ensures that performance gains are balanced with production-quality safety standards.