Fleet coordination
When more than one agent works the same repo and branch, Fleet gives them typed intents, exclusive leases, a conflict-classified episode log, and human escalation for the conflicts that matter.
Fleet coordination is for when more than one coding agent is working the same repository and branch at the same time. Instead of agents silently overwriting each other's edits, Memtrace gives them a shared coordination layer: typed intents announced before editing, exclusive leases for destructive changes, an episode log classified by conflict severity, and a human escalation path for the conflicts that shouldn't be resolved by an agent alone.
Overview#
The fleet surface is served in-process by Memtrace's own MCP server — backed by the memfleet-broker crate (intents, leases, episodes, CRDT, and provenance modules), attached to the same MemDB loopback port as the rest of the graph. There's no separate sidecar to run: if memtrace start is up, fleet coordination is available to any agent that calls the tools.
fleet_preflight doesn't only check for other agents — it also consults Cortex governance through the cortex_client bridge, so a "coast clear?" check surfaces both live peer conflicts and governing decisions in one call.
The 17 fleet_* tools#
The tools group into five families: intents, episodes, leases, escalations, and shared CRDT docs — plus a durable audit trail that spans all of them.
Intents
| Tool | Purpose |
|---|---|
fleet_publish_intent | Announce a typed intent before editing. Returns impact_preview (real graph blast radius of the touched symbols), active_conflicts (overlapping live intents from other agents), and an intent_id. |
fleet_status | Report the count of live, un-expired intents in the registry — a quick check that coordination is active. |
fleet_branch_context | Bundled session-start snapshot: your agent id, live peer intents, pending escalations, and recent peer episodes on the same branch. |
fleet_preflight | Read-only "is the coast clear?" check for a set of symbols before publishing an intent or committing an edit — no side effects. |
Episodes
| Tool | Purpose |
|---|---|
fleet_record_episode | Record an edit and get its CRDT conflict class (A/B/C) against live intents, plus a replan_hint and propagated blast radius. |
fleet_get_episode | Fetch a single recorded coordination episode by episode_id (ULID). |
fleet_query_episodes | List recorded episodes, optionally scoped to a symbol and/or filtered by conflict_class (A, B, or C) — use B/C as a conflict inbox. |
fleet_get_node_state | Coordination rollup for a single symbol: recent episodes, active overlapping intents, dominant intent kind, and a conflict density score. |
Leases
| Tool | Purpose |
|---|---|
fleet_acquire_lease | Request an exclusive lease on a set of symbols before a destructive edit. Returns granted or requested (queued behind a higher-priority holder); higher priority can preempt lower-priority holders. |
fleet_release_lease | Release a held lease by lease_id. The next queued requester for an overlapping scope is automatically granted. |
fleet_renew_lease | Extend a granted lease’s expiry by ttl_seconds from now. |
Human-in-the-loop escalations
| Tool | Purpose |
|---|---|
fleet_list_escalations | List the per-repo "needs human" queue: Class C conflicts escalated for a human to decide, newest first. |
fleet_get_escalation | Poll a single Class C escalation for the human’s decision. Pass your agent_id to get your_directive back: wait, proceed, defer, or review. |
fleet_resolve_escalation | Apply a human decision to a Class C escalation, recording the resolution and clearing it from the needs-human queue. |
fleet_submit_verdict | Submit a mediation verdict for a Class C conflict as the agent judge: reconcile, recommend a winner, or defer_to_human. |
Shared CRDT docs and audit
| Tool | Purpose |
|---|---|
fleet_ydoc_append | Leave a note on a symbol’s collaborative thread (intent, edit, conflict, or resolution) — a conflict-free CRDT log agents and humans share to discuss a conflict. |
fleet_ydoc_read | Read a symbol’s collaborative thread in append order. Omit symbol_id to read the whole repo’s thread. |
fleet_audit | Query the durable, append-only compliance trail: which engineer, via which agent product, did what, on which branch, when — survives forever, across machines. |
None of the 18 fleet_* tools count against your plan's query quota — coordination overhead is deliberately free so agents aren't discouraged from checking in.
Branch-scoped coordination#
Fleet coordination is scoped to a single (repo, branch) pair. Pass your session branch when you publish intents, record episodes, or check preflight — agents on a different branch of the same repo simply don't appear in your conflict view, and vice versa. Omit the branch and you fall into the shared default pool, which is the right choice only when you genuinely want to coordinate across everything.
Intents, TTL, and the "0 active agents" artifact#
Every published intent carries a 120-second TTL. An agent that's mid-task keeps its intent alive by continuing to interact with the fleet tools; once an agent goes quiet for longer than the TTL, its intent expires and stops showing up in other agents' conflict checks.
If fleet_status or the dashboard shows 0 active agents during a long build, test run, or any stretch where an agent isn't calling fleet tools, that's expected — the intent simply timed out. It does not mean coordination is broken or that the other agent disappeared.
Conflict classes and escalation#
When you call fleet_record_episode, Memtrace classifies the edit against every other agent's live intents on the same branch:
| Class | Meaning | What happens |
|---|---|---|
| A | Additive / safe — no meaningful overlap with another agent’s touched set. | Proceed. |
| B | Touched-set overlap — another agent’s intent or episode shares symbols with yours. | Re-read before proceeding; not necessarily destructive, but worth a second look. |
| C | Destructive overlap — a genuine collision on the same symbols with conflicting intent. | Defer or abandon; escalates to the needs-human queue. |
A Class C escalation blocks the agent until a human directive arrives. The blocked agent polls fleet_get_escalation with its own agent_id and gets back one of four directives:
- wait — no decision yet; keep polling.
- proceed — this agent was chosen as the winner; continue the edit.
- defer — another agent was chosen; stand down or rebase off their result.
- review — a free-text decision was made; read the
resolutionfield.
A human resolves the escalation with fleet_resolve_escalation (recording a free-text resolution and, optionally, a winner agent), or agents themselves can propose a resolution first via fleet_submit_verdict — reconciling with a merge plan, recommending a winner with a rationale and confidence score, or deferring straight to a human. The daemon decides what to do with submitted verdicts: auto-apply on safe agent consensus, recommend for a one-click human confirm, or escalate anyway.
From two agents to an audited resolution#
Fleet control room (dashboard)#
The Fleet page in the :3030 dashboard is the visual face of this whole layer. It renders a 3D fleet map as the overview, plus four classic sections underneath:
- Overview — the 3D fleet map with live agent nodes.
- Decisions — the escalation queue and resolutions.
- Work — active intents and in-flight episodes.
- Safety — leases and conflict density.
- Activity — fed by the coordination audit trail; against an older daemon that predates the audit endpoint, this section degrades to empty rather than erroring.