When multiple AI agents edit the same codebase at the same time, you get a distributed systems problem — non-deterministic timing, partial visibility, and shared mutable state. This document describes how Orkestrate solves it: the coordination protocol, the failure model, and the control loop that keeps agents productive without stepping on each other.
Four constraints that everything else is built on.
Before an agent edits a single file, it writes its objective, claimed paths, and plan to the shared coordination state. Other agents read that state to scope their own work. This isn't a best-practice recommendation — it's the mechanism that prevents two agents from silently rewriting the same module.
Hooks and telemetry capture what actually happened — file edits, tool calls, commits — without relying on agents to self-report. The system doesn't trust intent. It verifies behavior. When an agent edits a file it didn't claim, the system catches it and flags the overlap.
Orkestrate doesn't replace version control. It sits alongside it. Agents work on per-agent branches (orkestrate/<agent-id>/<slug>) and share durable code via fetch, rebase, and pull requests. Orkestrate is the coordination layer that tells agents what to work on. Git is where the actual code lives.
When two agents touch overlapping paths, the system emits a conflict_alert with the file, both agents, and what changed. It doesn't lock files. It doesn't roll back writes. It makes the collision visible and gives agents the context they need to resolve it. Throughput stays high. Collisions stay recoverable.
Every agent runs this cycle. It's designed to be boring — read, claim, work, update, repeat. If an agent crashes mid-cycle, the last state write is still valid. There's nothing to roll back.
Pull the current team state — every agent's objective, claimed paths, in-progress plan, recent file edits, and any active collision warnings. The response includes a stateHash that you'll need for the next write.
Declare your intent. Pick the smallest unclaimed path scope that covers what you need to do. Write your objective, plan, and claimed paths. Pass the stateHash you got from reading — if someone else wrote state between your read and your write, the system rejects and you re-read.
Do one focused unit of work. Telemetry hooks fire automatically — file_edit_observed when you edit, commit_observed when you commit. You don't need to report these. The system watches.
Record architecture decisions, design rationale, or anything that future agents in this workspace should know. This context outlives your session.
Mark completed items, adjust your plan, and narrow your path claims. If you're done, set status to idle. If you're blocked, say so. Then loop back to Read.
The most important boundary in the system. Observation and intention are separate pipelines that never cross.
Fire automatically. They capture what happened — not what was planned.
Require the agent to explicitly call them. They represent declared intent.
Every race condition and edge case has a deterministic response. The system doesn't guess. It rejects or preserves.
| Case | Signal | Response | Owner |
|---|---|---|---|
| Stale state write | expectedStateHash doesn't match | Rejected. Re-read state, merge your intent with whatever changed, retry with the fresh hash. | state handler |
| Cross-repo drift | canonicalRemote mismatch | Rejected. The agent is pointing at the wrong repository. State write blocked until the workspace binding matches. | repo identity |
| Parallel path overlap | file_edit_observed intersects a foreign claim | Both writes are preserved. A conflict_alert is emitted with the overlapping path, both agents, and the edit details. Nothing is dropped. | activity reconciler |
| Agent liveness ambiguity | Stale heartbeat vs. late disconnect event | Agent stays online until a disconnect event newer than its last heartbeat arrives. Prevents premature cleanup. | presence model |
| Duplicate sessions | Same external session ID from multiple streams | Merge attempt — adopt the heuristic session into the canonical one. Dedup by external ID within workspace scope. | session resolver |
| Out-of-order telemetry | Late-arriving events with older timestamps | Store everything immutably. Sort by createdAt at read time. Late events are never discarded. | telemetry ingest |
Orkestrate biases for explicit contracts over hidden automation. The initialize tool frames behavior. Read/write state is the coordination primitive. Git stays as durable truth. Telemetry stays as ground-truth observation.
You can understand what any agent is doing by reading its last state write. You don't need to trace telemetry or infer intent from diffs. That's the point — the system is legible at the coordination layer, even with dozens of agents running concurrently.
The system doesn't try to prevent all conflicts. It makes them visible, attributable, and recoverable. That's a deliberate trade — maximum throughput, minimum surprise.