All work

Agent orchestration / Case study

SwarmWeaver

Coordinate parallel work without competing file edits.

Type
Open-source engineering
Release
v1.0.0
Stack
Python 3.12 · DAG Scheduler · MCP JSON-RPC 2.0 · Concurrency Control
Automated tests
70

System architecture

  1. Conflict-Aware Topological Wave Compiler (swarmweaver/dag.py)
  2. File-Scope Lease Manager & Typed Blackboard (swarmweaver/leases.py, blackboard.py)
  3. SHA-256 Hash-Chained Checkpoint Journal & MCP Server (swarmweaver/checkpoint.py)
Three layers from the project’s architecture blueprint

01 / Problem

Why it exists

Parallel multi-agent coding and research swarms fail in production when two concurrent subagents edit overlapping files (silently clobbering changes), when a 15-step workflow crashes at step 12 and wastes all prior tokens, or when agents pass unvalidated prose across task boundaries.

02 / Design

How it works

Combine static conflict-aware wave partitioning (greedy graph coloring over read/write globs) with runtime FileScopeLeaseManager enforcement and SHA-256 checkpoint journaling.

  1. Conflict-Aware Topological Wave Compiler (swarmweaver/dag.py)

    Detects dependency cycles, computes critical-path latency, and partitions each topological level into conflict-free parallel sub-waves.

  2. File-Scope Lease Manager & Typed Blackboard (swarmweaver/leases.py, blackboard.py)

    Enforces SHARED_READ and EXCLUSIVE_WRITE locks on files/globs/AST symbols and validates inter-agent blackboard schemas.

  3. SHA-256 Hash-Chained Checkpoint Journal & MCP Server (swarmweaver/checkpoint.py)

    Replays completed DAG nodes deterministically on crash recovery with zero wasted tokens and exposes 4 JSON-RPC 2.0 MCP tools.

Static Graph-Coloring Wave Splitting Paired with Runtime Lease Enforcement
Context
Relying solely on runtime locks causes parallel subagents to stall in lock contention, while relying solely on static scheduling misses dynamic tool accesses.
Decision
Combine static conflict-aware wave partitioning (greedy graph coloring over read/write globs) with runtime FileScopeLeaseManager enforcement and SHA-256 checkpoint journaling.
Trade-offs
Requires tasks to declare read/write glob patterns upfront, but eliminates race conditions and achieves a 5.93x parallel speedup on 200-node graphs.
Verification
Verified across 70 pytest tests and a 4-part benchmark suite.
Security and operational constraints
  • Cryptographic SHA-256 lease tokens prevent unauthorized lock releases across concurrent agent threads.
  • Tamper-evident SHA-256 checkpoint hash chain (verify_integrity()) blocks corrupted or modified state injection during workflow resume.
  • Strict TypedBlackboard input/output schema validation prevents unvalidated agent handoffs.
  • No two tasks assigned to the same execution sub-wave ever hold overlapping EXCLUSIVE_WRITE or READ/WRITE file-scope patterns.
  • Deadlocks are impossible during multi-file lease acquisition because scopes are acquired in canonical lexicographical order.
  • Any tampering in the checkpoint JSONL journal breaks the SHA-256 hash chain and halts workflow resume before execution.

03 / Evidence

How to verify it

Repository-reported / Collision Prevention & Resume Savings

0 Race Conditions · 70% Tokens Saved

100% file-collision prevention across 50 parallel conflicting tasks and 0.0072 ms/node checkpoint replay

Reproduce from the command line
git clone https://github.com/codesphere-u/swarmweaver.git
cd swarmweaver && pytest -v
python -m swarmweaver.cli demo && python -m swarmweaver.cli benchmark
View source on GitHub
Next case study · AI verification TruthGate Check an agent’s claims against sources and code.