Runtime map

Pipeline lifecycle

runSwarm sets up fresh runs; resumeSwarm rehydrates interrupted ones. Both hand a shared runtime core to executeRun. Each run resolves config and agents, picks a harness per agent, runs rounds in parallel, folds the prior packet into the next directive between rounds, persists everything append-only, and finishes with a deterministic synthesis.

1. Resolve config + agents. CLI flags > project config > preset defaults, then each agent's runtime is resolved.
2. Resolve harnesses. Each agent picks a harness: agent.harness → run-level --backend → agent.backend.
3. Round execution. Agents run with a default concurrency of 3 and one format-repair retry; output is validated against the Zod AgentOutputSchema.
4. Between rounds. The next directive is templated (off) or produced by the orchestrator agent.
5. Synthesis. Fully deterministic - no LLM call - consensus, top recommendation, shared risks, deferred questions.

Backend and harness layering

A backend is the run-level dial (claude or codex); a harness is the per-agent dispatch target (claude, codex, opencode, or rovo). They are deliberately separate. The run-level backend still names the run metadata, but each agent's dispatch goes through the adapter resolved from its own harness, so a swarm can mix harnesses in a single run.

Registries

Agents and presets load from three scopes - project, user, then bundled - with first match winning and the current .agent-swarm/ root searched before the legacy .swarm/ root. Markdown agents use YAML frontmatter validated against the same schema as .yml agents.

Schemas

Every cross-boundary contract is a Zod schema - no hand-rolled types for anything that crosses the disk or wire boundary. Key schemas include AgentOutputSchema, OrchestratorOutputSchema, RunManifest, RunCheckpoint, and MessageEnvelope. BackendId and HarnessId are separate schemas on purpose.

Persistence

Three append-only writers fan out from OutputRouter: an artifact writer (round folders + manifest), a ledger writer (events.jsonl + messages.jsonl), and a checkpoint writer (checkpoint.json). Because writes are incremental, a failed run leaves inspectable artifacts and state for recovery; user-facing resume tooling is future work, not part of the alpha contract.