How SwarmForge Handles Agent Conflicts: Detection, Resolution & Escalation

SwarmForge resolves agent conflicts through Git merge detection, delegate resolution to the receiving agent, and operator escalation for semantic conflicts.

Parallel agents in multi-agent systems inevitably clash when modifying shared files. The SwarmForge orchestration framework treats conflicts as expected outcomes rather than failures, routing all coordination through a handoff daemon that enforces Git-based conflict detection and human escalation protocols. This article examines the exact mechanics of conflict handling in the unclebob/swarm-forge repository.

---

Conflict Detection via Git Merge Monitoring

SwarmForge never permits agents to directly manipulate tmux sockets or repositories. Instead, the handoff daemon serializes all coordination through Git handoffs. When two parallel agents modify overlapping files, the receiving agent's helper scripts surface the conflict through explicit merge failure detection.

In swarmforge/scripts/swarmforge.bb (lines 33–34), the launcher codifies this policy:

"If merge_and_process.sh or ready_for_next reports a merge conflict, resolve the conflicted files, git add, and commit. Do not invent git merge."

The helper scripts merge_and_process.sh and ready_for_next.sh execute git merge and monitor exit status. A non-zero exit signals conflict—no automatic merging is attempted. The conflict propagates to the agent runtime for manual resolution.

# ready_for_next.sh – generic receiver that surfaces conflicts

#!/usr/bin/env bash
set -euo pipefail

# …fetch handoff, apply it…

if ! git merge "$COMMIT"; then
  echo "Merge conflict – ask operator"
  pack_dashboard_request.sh clarify ./tmp/conflict-question.txt
fi

---

Agent-Led Resolution Workflow

The receiving agent bears full responsibility for conflict resolution. This mirrors standard Git workflows and ensures single-source-of-truth integrity:

1. Inspect conflict markers in affected files
2. Edit to resolve overlapping changes
3. Stage resolved files via git add …
4. Commit the resolution with descriptive message

The resolution commit becomes part of the permanent handoff chain, visible to downstream agents.

;; Example: agent handling incoming handoff with merge conflict
(defn handle-incoming-handoff [ctx handoff]
  (let [{:keys [commit]} handoff]
    (sh "git" "checkout" commit)               ; apply incoming commit
    (let [{:keys [exit out err]} (sh "git" "merge" "HEAD")]
      (if (zero? exit)
        (println "Merge succeeded")
        (do
          (println "Merge conflict detected – resolving")
          ;; Resolve manually then:
          (sh "git" "add" ".")
          (sh "git" "commit" "-m" "Resolved conflict from handoff")
          (println "Conflict resolved and committed"))))))

---

Operator Escalation for Semantic Conflicts

Syntactic merges (overlapping file edits) resolve through Git. Semantic conflicts—contradictory requirements, ambiguous specifications, or test failures—require human judgment.

As specified in swarmforge/handoff-protocol.md (lines 96–99):

"When blocked by ambiguity, contradiction, or test/specification conflict, an agent should ask the operator."

Agents invoke pack_dashboard_request.sh to submit clarification requests through the dashboard UI. The system pauses until operator response arrives, preventing autonomous resolution of ambiguous requirements.

---

Audit Trail and Chain Forwarding

Every handoff—including conflict resolutions—generates immutable records in .swarmforge/handoffs/. The daemon:

• Copies handoffs to each recipient's inbox
• Logs resolution events with timestamps
• Enforces chain forwarding so downstream agents receive resolved states

The SwarmForge constitution mandates that intermediate roles always forward a git_handoff after completing work, even for metadata-only changes (swarmforge/handoff-protocol.md, lines 60–66). This guarantees propagation of conflict resolutions through the agent pipeline.

---

Key Source Files

File Path	Purpose
swarmforge/scripts/swarmforge.bb	Core launcher defining conflict-handling policy (line 33–34)
swarmforge/handoff-protocol.md	Full handoff daemon specification, escalation rules, and audit logging
swarmforge/constitution/articles/handoffs.prompt	Governance of note handoffs vs. operator escalation
scripts/merge_and_process.sh	Merge execution and conflict reporting
scripts/ready_for_next.sh	Generic receive script with conflict detection

---

Summary

• Conflict detection relies on git merge exit status in helper scripts—no automatic merging occurs
• Resolution responsibility falls to the receiving agent through standard Git workflows
• Operator escalation handles semantic conflicts via dashboard requests per the handoff protocol
• Audit logging persists all handoffs in .swarmforge/handoffs/ with full chain forwarding
• Constitutional rules enforce git_handoff propagation to maintain resolved state visibility

---

Frequently Asked Questions

What triggers a conflict in SwarmForge?

Parallel agents modifying overlapping files in the same worktree trigger Git merge conflicts when the receiving agent attempts to integrate the incoming handoff. The ready_for_next.sh and merge_and_process.sh scripts detect this through non-zero git merge exit codes.

Can agents automatically resolve merge conflicts?

No. The launcher explicitly prohibits autonomous merging with the directive "Do not invent git merge". Agents must manually inspect conflict markers, edit files, stage with git add, and commit the resolution.

How does SwarmForge handle contradictory requirements?

Semantic conflicts—ambiguous specs, contradictory requirements, or test failures—trigger operator escalation. Agents submit dashboard requests via pack_dashboard_request.sh and await human clarification rather than choosing autonomous resolutions.

Where are conflict resolutions recorded?

All handoffs including conflict resolutions are stored in .swarmforge/handoffs/, copied to recipient inboxes, and logged by the handoff daemon. This provides reproducible audit trails of who resolved what and when.

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