How Does Batch Receive Mode in SwarmForge Process Multiple Queued Handoffs?

Batch receive mode in SwarmForge aggregates handoffs sharing the same priority into a unique batch directory, merges any git payloads, and emits them as a single logical task for atomic processing by the receiving role.

SwarmForge, an open-source workflow orchestration system from the unclebob/swarm-forge repository, supports two distinct work reception strategies: individual task processing and batch processing. When a role is declared with batch receive mode in the configuration, the system groups pending handoffs from the inbox queue and processes them as a coordinated unit rather than isolated tasks.

Configuration and Validation of Receive Modes

The swarmforge/scripts/swarmforge.bb file handles configuration parsing through the receive-fields function (lines 49-58). When parsing a role definition, the parser extracts the token following the worktree name. If this token is batch, the system configures the role for batch processing; otherwise, it defaults to task mode.

During the validation phase, the validate-window! function (lines 78-80) enforces that only task or batch are valid values for receive-mode. Any other value triggers a validation error, ensuring strict type safety for the reception behavior.

Gathering and Prioritizing Queued Handoffs

The core batch processing logic resides in swarmforge/scripts/ready_for_next_batch.bb. First, the script scans the .swarmforge/handoffs/inbox/new directory using the handoff-files helper to collect all *.handoff files waiting in the queue.

Next, the system groups these files by their priority header. The batch-priority logic identifies the highest priority level present, and selected-files filters the handoffs that match this priority (lines 66-70). This grouping ensures that urgent work is batched together before lower-priority items.

Batch Directory Creation and Git Merge

Once handoffs are selected, the new-batch-dir function generates a unique identifier using the pattern batch_<timestamp>_<seq> and creates this directory inside the in_process work area (lines 33-38). Each selected handoff file is then moved from the inbox into this batch folder via fs/move.

During the move operation, the system updates metadata headers on each handoff using set-header!. The script adds dequeued_at timestamps and task_base_commit references to track when the handoff entered processing and its git state (lines 71-77).

After physical relocation, the merge-batch! function iterates through the batch contents and calls merge-git-handoff! for every file. This applies any git_handoff payloads to the working directory, ensuring the role receives the accumulated code changes from all batched handoffs.

Emission and Resolution of Batch Tasks

Following successful merging, the print-batch function (lines 98-110) emits a structured summary to standard output. This includes the BATCH: line showing the full path to the batch directory, a COUNT: of items, and the TASK_NAME: derived from the first handoff's task header. Each item in the batch is enumerated with BATCH_ITEM: entries for downstream parsing.

When the receiving role queries for the next work unit via ready_for_next.sh, the top-batch-task and top-batch-task-id functions in swarmforge/scripts/swarm_handoff.bb (lines 44-48) extract the logical task name from the first handoff's headers. This allows the role to treat the entire batch as a single named unit while retaining access to individual handoffs within the batch directory.

Completion and Cleanup

After the role finishes processing, the done_with_current_batch.bb helper script removes the batch directory from in_process and archives it to the completed inbox. This atomic cleanup ensures that partial batch processing cannot occur; the batch is either fully processed or remains in the active queue.

Practical Implementation Example

Configure a role for batch processing in your swarmforge.bb:

;; Role "cleaner" receives work in batch mode with forward-only policy
cleaner  codex  worktree1  batch  forward-only

Execute the batch receiver:

bb swarmforge/scripts/ready_for_next_batch.bb

Expected output:

BATCH: .swarmforge/handoffs/inbox/in_process/batch_20260824T150500Z_000001
COUNT: 3
TASK_NAME: Command Syntax
BATCH_ITEM: 1
  TASK: ...
BATCH_ITEM: 2
  TASK: ...
BATCH_ITEM: 3
  TASK: ...

This command groups all priority-matched handoffs, creates the batch directory, merges git changes, and presents the consolidated work unit for processing.

Summary

• Configuration: Set receive-mode batch in swarmforge.bb to enable batch processing; the parser defaults to task if unspecified.
• Grouping: The ready_for_next_batch.bb script groups handoffs from .swarmforge/handoffs/inbox/new by matching priority headers.
• Atomic Bundling: Handoffs move into a unique batch_<timestamp>_<seq> directory under in_process, receiving dequeued_at and task_base_commit metadata.
• Git Integration: The merge-git-handoff! function applies all git payloads within the batch before the role receives the work.
• Logical Unification: top-batch-task in swarm_handoff.bb treats the batch as a single task while preserving individual handoff granularity.

Frequently Asked Questions

What is the difference between task and batch receive mode in SwarmForge?

Task mode processes handoffs individually, presenting each as a separate work unit to the role, while batch receive mode aggregates multiple handoffs sharing the same priority into a single logical task. In batch mode, the role receives a directory containing all related handoffs and processes them atomically, which is ideal for coordinated operations across multiple work items.

How does SwarmForge determine which handoffs belong to the same batch?

The system evaluates the priority header of each handoff file in .swarmforge/handoffs/inbox/new. The batch-priority logic selects the highest priority level present in the queue, and all handoffs sharing that priority value are bundled into the same batch. Lower priority handoffs remain in the inbox for future batch cycles.

What happens to git handoffs during batch processing?

During batch creation, the merge-batch! function in ready_for_next_batch.bb calls merge-git-handoff! for every handoff in the batch. This applies each handoff's git_handoff payload sequentially to the working directory, ensuring the receiving role sees the cumulative state of all code changes without needing to manually merge individual contributions.

How is a batch marked as complete after processing?

Once the role finishes working on the batch, the done_with_current_batch.bb script performs cleanup by removing the batch directory from in_process and moving it to the completed inbox. This helper ensures that batch processing is atomic—either all handoffs in the batch are processed and archived, or the batch remains active in the processing queue.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}