Sessions on several machines work one repository without colliding

Majordomus runtimes of one repository — on one machine or several — discover each other, link through a signed handshake, and share sessions, claims, handovers and reviews through one replicated journal that survives disconnects, crashes and partitions.

status: feature status: stable
domain: Coordination
on the homepage: featured

What it does

Several AI coding sessions — two terminals on a laptop, a desktop, a build machine — work one repository. With an enabled mesh declaration each checkout's server is a runtime of the mesh: it announces itself (signed, over multicast, a broadcast fallback, a rendezvous, or declared seeds), and when it finds a runtime of the same repository whose key it trusts, the two open a link through a signed handshake. From then on, every heartbeat, they exchange what the other lacks of one journal of signed events:

sessions — who is working, with which client, on which issue, branch and head; the peer board's announcements are projected in automatically;
claims — an exclusive claim made on one machine refuses an overlapping claim on every linked machine, claim_conflict naming the claim it meets;
handovers — mesh handover publish on one machine, mesh handover consume on another, and the record lands where majordomus handover --resolve finds it;
reviews — ask a named runtime for a review and see its answer on your machine.

Every linked runtime folds the same events into the same state and prints the same digest. A runtime that stops beating — killed, crashed, cut off — expires on its peers within the declared expiry, its claims stop excluding, and when it comes back it reconnects as the same runtime. majordomus mesh peers, mesh state, mesh verify, /api/v1/mesh/*, the MCP tools and the Cockpit's Mesh page show machines, runtimes, sessions, claims, links and why anything was refused.

What it does not do

It does not trust the network: discovery finds candidates and grants nothing, a link needs the same repository, a compatible protocol and a trusted key, and nothing a peer sends executes anything. It is not a strongly consistent lock service — during a partition both sides may claim the same scope, and the conflict is named with one winner after healing. It does not encrypt: links belong on a private network or an overlay such as a tailnet. It does not cross a WAN, traverse NAT or copy source files — git owns the code; the mesh carries what people and agents say about their work. And it sends nothing until a person commits enabled: true and lists the keys to trust.

How it works

The capability modules of the executable this feature names, each with the capabilities it composes. The interfaces each one reaches are listed under Interfaces below: they are projections of one declaration, not separate registrations.

Mesh mesh experimental

The mesh of this process: discovery — authenticated observations of other running Majordomus instances in one registry — and cooperation — authenticated links to trusted runtimes of the same repository, replicating sessions, claims, handovers and reviews through one journal every runtime folds into the same state. Discovery grants nothing; a link is admitted per peer, and nothing a peer sends executes anything here.

Claim a scope across the mesh command
Cooperation, at a glance query
The mesh self-check query
The cooperation journal query
The host firewall, as the mesh needs it query
Admit the mesh through the host firewall command
Consume a handover from the mesh command
Publish a handover to the mesh command
This machine's node identity query
Open a link (the handshake) command
One sync round of a link command
The discovered nodes query
One runtime query
Who cooperates, machine by machine query
Register with this node's mesh command
Release a claim command
Answer a review request command
Ask the mesh for a review command
Withdraw a review request command
Close a session on the mesh command
Open or update a session on the mesh command
The state every linked runtime converges on query
The mesh, at a glance query
Prove cooperation now command

The objects it is made of

Kinds of the layer. Each is a schema, a source class and a file on disk; the number beside it is what this repository holds today, counted at build time.

mesh-declaration1

Where it sits

domain: Coordination — Every worker declares the paths it will touch, sees who else is working and where, and hears about a collision before it is committed.
areas of work: coordination
names: Coordination
named by: Models Reasoning

Interfaces

Each capability behind it, on every interface it is projected onto. A link goes to this site's reference for that interface; an HTTP route and an MCP tool are answered by a running majordomus serve, not by this site.

The capabilities behind this feature, by interface
capability	command line	HTTP	MCP tool
mesh.claim	—none	POST /api/v1/mesh/claims	majordomus_mesh_claim
mesh.cooperation	—none	GET /api/v1/mesh/cooperation	majordomus_mesh_cooperation
mesh.doctor	majordomus mesh doctor	GET /api/v1/mesh/doctor	majordomus_mesh_doctor
mesh.events	—none	GET /api/v1/mesh/events	majordomus_mesh_events
mesh.firewall	majordomus mesh firewall	GET /api/v1/mesh/firewall	majordomus_mesh_firewall
mesh.firewall.apply	majordomus mesh firewall apply	—none	—none
mesh.handover.consume	—none	POST /api/v1/mesh/handovers/consume	majordomus_mesh_handover_consume
mesh.handover.publish	—none	POST /api/v1/mesh/handovers	majordomus_mesh_handover_publish
mesh.identity	majordomus mesh identity	GET /api/v1/mesh/identity	majordomus_mesh_identity
mesh.link.hello	—none	POST /api/v1/mesh/link/hello	—none
mesh.link.sync	—none	POST /api/v1/mesh/link/sync	—none
mesh.nodes	—none	GET /api/v1/mesh/nodes	majordomus_mesh_nodes
mesh.peer	—none	GET /api/v1/mesh/peer	majordomus_mesh_peer
mesh.peers	—none	GET /api/v1/mesh/peers	majordomus_mesh_peers
mesh.register	—none	POST /api/v1/mesh/register	majordomus_mesh_register
mesh.release	—none	POST /api/v1/mesh/claims/release	majordomus_mesh_release
mesh.review.answer	—none	POST /api/v1/mesh/reviews/answer	majordomus_mesh_review_answer
mesh.review.request	—none	POST /api/v1/mesh/reviews	majordomus_mesh_review_request
mesh.review.withdraw	—none	POST /api/v1/mesh/reviews/withdraw	majordomus_mesh_review_withdraw
mesh.session.close	—none	POST /api/v1/mesh/sessions/close	majordomus_mesh_session_close
mesh.session.open	—none	POST /api/v1/mesh/sessions	majordomus_mesh_session_open
mesh.state	—none	GET /api/v1/mesh/state	majordomus_mesh_state
mesh.status	—none	GET /api/v1/mesh	majordomus_mesh
mesh.verify	—none	POST /api/v1/mesh/verify	majordomus_mesh_verify

in the Cockpit, of a running server: /cockpit/mesh Mesh

Evidence

What is guaranteed

Each claim this feature names, with the status its row declares, the verdict the recorded runs support, and the test that settles it.

declared status: guaranteed recorded evidence: not run Two runtimes of one repository link only through a signed, replay-protected handshake that checks protocol, repository identity and trust, and every refusal is typed and visible apps/majordomus-cli/tests/mesh_cooperation.rs
declared status: guaranteed recorded evidence: not run An exclusive claim made on one runtime excludes an overlapping claim on every linked runtime, and concurrent claims resolve to one named winner everywhere apps/majordomus-cli/tests/mesh_cooperation.rs
declared status: guaranteed recorded evidence: not run Runtimes serving different repositories never form a cooperative link, even when they discover each other apps/majordomus-cli/tests/mesh_cooperation.rs
declared status: guaranteed recorded evidence: not run A runtime that stops beating — crashed, killed or partitioned — expires on its peers within the declared expiry, its claims stop excluding, and its restart reconnects as the same runtime without a duplicate apps/majordomus-cli/tests/mesh_cooperation.rs
declared status: guaranteed recorded evidence: not run Runtimes linked only through a relay converge on one state digest, each event held once, with no replication loop apps/majordomus-cli/tests/mesh_cooperation.rs
declared status: guaranteed recorded evidence: not run Separate Linux nodes on a real network discover each other by multicast, link, share claims and handovers, and recover from a partition and a crash, in a lab CI runs test/cases/414_mesh_lab_evidence.sh
declared status: guaranteed recorded evidence: not run A discovered node — trusted or not — gains no execution, no authorization and no write surface; trust labels records under an explicit policy that defaults to deny_unknown apps/majordomus-cli/tests/mesh.rs
declared status: guaranteed recorded evidence: not run Every discovery observation converges into one bounded registry, deduplicated by node and runtime identity across sources, replay-protected per instance, and every surface projects that registry and holds no peers of its own apps/majordomus-cli/tests/mesh.rs
declared status: guaranteed recorded evidence: not run No mesh discovery socket opens until the repository commits an enabled mesh declaration, and a disabled or absent declaration is reported as the reason, not an error apps/majordomus-cli/tests/mesh.rs

The rules that hold it

blocking The mesh observes nodes; it authorizes nothing and holds one registryproject.mesh-is-observation-not-authority
blocking Mesh cooperation is admitted per link, replicated through one journal, and projected by every surface alikeproject.mesh-cooperation-is-authenticated

The decisions behind it

adr-0050Mesh peer discovery is provider-based observation with authenticated node identity proposed
adr-0067Mesh cooperation is authenticated links between runtimes and one replicated journal folded the same way everywhere proposed

Using it

From the executable's command line

The synopsis of each, as the executable's own help prints it.

majordomus mesh identity [OPTIONS]
This machine's node identity, public half only; absent is an answer, not an error
majordomus mesh doctor [OPTIONS]
Prove the mesh prerequisites on this machine alone: declaration, identity, sockets, multicast, broadcast, the protocol end to end, and the host firewall
majordomus mesh firewall [OPTIONS] [COMMAND]
What the host firewall must admit for the declared mesh and whether it does; `apply` admits it, as root
majordomus mesh firewall apply [OPTIONS]
Run the commands that admit the plan on this host's firewall; needs root, and exits 10 when it refuses or the firewall still does not admit the mesh

Where this page comes from

the file: .ai/repo/features/mesh.md
the same answer: majordomus product show mesh
read further: Majordomus Mesh