v0.2.0 — substrate hardened

What's new

Added

• Orphan recovery (swarm_lib.orphan) — heartbeat write + reap() returning stale claims to pending/. New swarm-cli heartbeat + swarm-cli reap subcommands. worker_loop.sh runs a background heartbeat keeper while alive.
• Status lock — fcntl.flock advisory lock around the status.json read-modify-write. Fixes a real concurrency bug where N concurrent complete() calls silently dropped entries from completed_tasks (caught by the new multi-worker test).
• Cross-filesystem startup check — CrossFilesystemError raised when pending//claimed//done//failed/ span multiple st_dev. Prevents os.replace silently degrading to copy+unlink.
• swarm-cli ls — human-readable run summary (pending/claimed/done/failed counts, current next step, last completed task, in-flight workers). Scans ~/.swarm/* when --run-dir omitted. --json mode for scripting.
• Streaming log artifact — handlers can append progress to $SWARM_LOG_PATH (a tail-friendly .log next to the artifact).
• HMD triage example (examples/hmd-triage/) — cheap-classify → conditional-escalate pattern with a working stub.
• Multi-worker correctness test — threaded + subprocess claimants + reaper-during-drain. 14 new tests; 42 total passing.
• Real docs — full rewrite of README + landing page covering the three failure modes (context starvation, sync tool-call blocking, chat-history-as-state), three primitives, when to use it, comparison vs Celery / Airflow / Temporal / LangChain / GitHub Actions, production deploy shape, and anti-fleet handler hygiene.
• swarm.mabus.ai is the canonical site URL (was mabus.ai/swarm/).

Internal

• Site Astro config: base: '/swarm' → root; site: 'https://swarm.mabus.ai'.
• Package version bumped from 0.2.0.dev0 to 0.2.0.

Inspiration

The Inkcloud Architecture Post-Mortem ("Unix Swarm Blueprint") — direct inspiration for the Yield Rule, peer-agent model, and filesystem-as-orchestrator framing. The cautionary "Fleet" incident is why DESIGN.md has an anti-fleet section.

---

• Docs: https://swarm.mabus.ai
• Design spec: DESIGN.md
• 42 tests passing (claims, status, orphan, multi-worker)

v0.1.0 — substrate complete

First public release. Three primitives shipped and validated end-to-end.

What's in v0.1.0

• swarm_lib.claims — atomic-rename queue primitives (enqueue / try_claim / complete) backed by POSIX os.replace. Multiple workers race for tasks; exactly one wins.
• swarm_lib.status — status.json checkpoint state with strict schema versioning, idempotent append_completed, additive-merge write, fresh initialize.
• swarm_lib.cli — swarm-cli console entry point exposing all primitives for shell consumers. jq-friendly single-line JSON output.
• swarm_lib/worker_loop.sh — generic consumer loop that ties everything together. Polls a queue, claims atomically, invokes a user-supplied handler, marks done/failed.
• examples/seven-step-chain/ — Tribunal-shaped reference consumer (driver + self-chaining handler) demonstrating the substrate against a real-world multi-step workflow.

What's validated

48 total smoke checks pass across the substrate:

• 14 unit-level (claims + status + claims↔status integration)
• 13 CLI + worker_loop end-to-end
• 21 seven-step chain (full Tribunal-shaped workflow runs to completion)

Site + docs

• Site: https://dpdanpittman.github.io/swarm-lib/ (will migrate to mabus.ai/swarm/ once the Caddy block lands)
• Design spec: DESIGN.md / DESIGN.html

Next: v0.2

• HMD triage layer (cheap-model classify → expensive-model escalation)
• Orphan cleanup daemon
• A real Tribunal port using this substrate (in the dpdanpittman/tribunal repo)