How the Priority Field Is Processed in Swarm-Forge Handoff Message Files

The priority field in Swarm-Forge handoff messages is parsed from file headers, validated as a two-digit string ranging from 00 to 99, embedded into filenames to enable lexical queue ordering, and used to group batch tasks by matching priority values.

The unclebob/swarm-forge repository implements a handoff protocol where agents communicate through structured message files. Understanding how the priority field is processed is essential for debugging task ordering and ensuring proper workflow orchestration across the swarm.

Parsing and Validating the Priority Header

When a handoff file is read, the system extracts the priority value from the file headers and validates it against strict formatting rules.

Extracting the Header Value

In swarmforge/scripts/swarm_handoff.bb, the priority is retrieved from the parsed headers map:

(let [priority (get headers "priority")]

This extraction occurs during the initial file read operation (line 176), where the handoff file headers are parsed into a Clojure map structure.

Validating the Format

The extracted value must conform to a two-digit numeric format. The valid-priority? function enforces this using a regular expression pattern:

(defn valid-priority? [priority]
  (boolean (re-matches #"[0-9][0-9]" priority)))

(see swarmforge/scripts/swarm_handoff.bb lines 89-90)

If the priority is missing, blank, or fails to match the pattern, the system raises an error immediately:

(when (or (str/blank? priority)
          (not (valid-priority? priority)))
  (fail! 1 (format "Header 'priority' must be two digits from 00 to 99; got '%s'." priority)))

This validation is also re-exported in swarmforge/scripts/handoff_lib.bb (line 65) for use in command-line validation tools.

Filename Construction and Queue Ordering

The priority value directly influences the physical filename, creating a sorting mechanism that requires no additional metadata queries.

Embedding Priority into Filenames

The system constructs handoff filenames with the priority as the leading component:

(def filename
  (str priority "_" timestamp-id "_" sequence
       "_from_" sender "_to_" recipient-slug ".handoff"))

(see swarmforge/scripts/swarm_handoff.bb line 278)

This naming convention ensures that a standard lexical sort of the directory contents automatically orders tasks by priority. According to the handoff-protocol.md documentation (lines 77-78):

"Lower priority numbers are processed first. priority is two digits from 00 through 99."

Practical File Creation Example

When creating a handoff file manually, the priority appears in both the filename and the internal header:

cat > 10_20260615T000001Z_000001_from_sender_to_receiver.handoff <<'EOF'
type: git_handoff
to: receiver
priority: 10
commit: abcdef1234567890
EOF

Batch Selection by Priority

When processing tasks in batches, the system uses the priority to ensure atomic handling of related handoffs.

In swarmforge/scripts/ready_for_next_batch.bb (lines 134-136), the algorithm selects the first file to determine the target priority, then filters the queue for all files sharing that same priority:

(let [batch-priority (header-value (first new-files) "priority" "50")
      selected-files (filter #(= batch-priority
                                (header-value % "priority" "50"))
                            new-files)]

This ensures that a batch consists only of tasks with identical priority levels, preventing higher-priority tasks from being blocked by lower-priority ones in mixed batches.

Default Priority Handling

When reading handoff files that may lack explicit priority headers, the system falls back to a default value of "50" (mid-range):

(header-value file "priority" "50")

(see swarmforge/scripts/ready_for_next_task.bb line 78)

This default ensures backward compatibility and prevents null pointer exceptions while maintaining predictable ordering behavior—tasks without explicit priority sort into the middle of the queue rather than the beginning or end.

Summary

• Validation: The priority must be a two-digit string from 00 to 99, validated by the valid-priority? function using regex pattern #"[0-9][0-9]".
• Filename Integration: Priority prefixes the filename ({priority}_{timestamp-id}_{sequence}_from_{sender}_to_{recipient}.handoff) to enable lexical sorting.
• Queue Ordering: Lower numbers indicate higher precedence, with 00 processed before 99.
• Batch Processing: Tasks are grouped by matching priority values before execution, as implemented in ready_for_next_batch.bb.
• Default Value: Missing priorities default to "50" to maintain queue stability.

Frequently Asked Questions

What happens if a handoff file has an invalid priority value?

The system raises an immediate error with exit code 1 and a descriptive message stating that the header must be two digits from 00 to 99. This validation occurs in swarm_handoff.bb before any file operations proceed.

How does Swarm-Forge handle files without a priority header?

When a priority header is absent, the header-value function returns the default value "50" as defined in ready_for_next_task.bb. This places unprioritized tasks in the middle of the processing queue.

Why is priority embedded in the filename rather than stored in metadata?

Embedding priority in the filename (10_20260615...) allows the operating system's native lexical sorting to order tasks correctly without requiring the system to open and parse each file's contents. This design optimizes performance when scanning large directories of handoff messages.

Can priority values be compared numerically or only as strings?

While stored as two-digit strings for lexical sorting, the protocol treats them as numeric values conceptually (00-99). The validation regex #"[0-9][0-9]" ensures they can be parsed as integers if needed, though the core sorting relies on string comparison of the filename prefixes.

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