the-mesh-works-out-of-the-box — The mesh works out of the box: trusted machines find each other by every means and their sessions cooperate from the first turn

•ACTIVE 3 of 8 issues done

ready

4

blocked

1

active

0

verify

0

done

3

cancelled

0

Problem

On 2026-10-10 the owner called mesh cooperation tragic and ordered it to work out of the box, by every discovery means, from the moment an LLM client, the MCP server or `majordomus serve` starts. A read of the code found six gaps that no existing milestone covers: no Tailscale discovery (the tailnet is reached only through 100.x addresses hand-written in .ai/repo/mesh/majordomus.yaml); a server binds and advertises 127.0.0.1 unless told otherwise, so two machines on default settings never dial each other (apps/majordomus-cli/src/cli.rs:3355-3362, mesh/address.rs:39-45); `majordomus init` ships no mesh declaration, so a fresh repository has no mesh at all; a linked worktree with no server of its own has no cooperation (`mesh handover publish` answered 'cooperation inactive'); mesh.state and mesh.peers return 56-134 kB with no filter; and a review request has no body, cannot be closed and never expires.

Outcome

A trusted machine that starts any Majordomus surface in a repository with the mesh declared is linked to every other trusted machine on the LAN or tailnet without a hand-written address, every worktree takes part, and what the mesh holds can be read in one tool answer.

Current state

Multicast on one LAN segment and five hand-written rendezvous hubs; loopback-bound servers; no declaration in a fresh repository; worktrees and review requests outside the loop.

Desired state

Tailscale, multicast, broadcast and rendezvous discovery; a mesh-enabled server reachable on the tailnet and LAN under the trust list; init that declares the mesh and enrols the machine's key; worktrees that cooperate through the primary's runtime; bounded, filterable mesh reads; a review lifecycle that ends.

Scope

• apps/majordomus-cli/src/mesh
• apps/majordomus-cli/src/capability/builtin/mesh.rs
• apps/majordomus-cli/src/cli.rs
• apps/majordomus-cli/src/shared.rs
• apps/majordomus-cli/src/lease.rs
• apps/majordomus-cli/src/commands
• share/skeleton
• share/schemas/majordomus/mesh-declaration
• lib/capture.sh
• docs/MESH.md
• test/cases

Out of scope

• Trusting a machine nobody listed: runtime-trust (I2261) keeps an unlisted clone off the mesh, and nothing here weakens it.
• Session start, briefing and Codex/Gemini participation: every-session-joins-the-mesh (I2285-I2292).
• Assigning and executing work on a peer: mesh-peers-execute-assigned-work (I2332-I2336).

Acceptance criteria

• Two trusted machines on one tailnet, each with a fresh `majordomus init` plus enrolment, link with no address written by hand
• A server whose mesh is enabled is reachable from a trusted peer on the tailnet and refuses an untrusted one
• A worktree of a checkout whose primary runs a server publishes a handover and a claim
• mesh.state and mesh.peers answer a filtered summary under 16 kB
• A review request carries a body, and can be withdrawn or expire

Validation

• bin/majordomus plan validate
• cargo test --lib mesh::

Evidence required

• two_machines_link_out_of_the_box

Risks

• It builds on runtime-trust and on I2123 (PR #860), which are not on master yet: I2411 lands after them.
• Binding beyond loopback widens what can reach a server: it waits for the remote-caller restrictions of runtime-trust (I2123, #860) and is refused for a node the trust list does not name.

Issues

Each one is an execution contract with its own acceptance criteria, validation command and required evidence. The wave column is the layer of the dependency graph it sits in.

The graph

flowchart LR
    I2410["I2410<br/>A trusted machine on the tailnet is found through Tailscale, with no address written by hand"]:::ready
    I2411["I2411<br/>A server whose mesh is enabled is reachable on the tailnet and the LAN, and only by a trusted peer"]:::ready
    I2412["I2412<br/>`majordomus init` declares the mesh and enrols this machine's key, so a fresh repository cooperates"]:::ready
    I2413["I2413<br/>A linked worktree cooperates through its repository's running server, and a start that cannot ensure one says why"]:::done
    I2414["I2414<br/>mesh.state and mesh.peers answer a filtered summary that fits one tool answer"]:::done
    I2415["I2415<br/>A mesh review request carries a body, can be withdrawn, and expires"]:::done
    I3835["I3835<br/>A node the mesh lists as trusted and present but cannot link is said so, with why, on every surface that names it"]:::ready
    I3837["I3837<br/>A case that enables the mesh declares its tailnet provider off, so it stays hermetic on a machine that runs Tailscale"]:::blocked
    I2410 --> I3837
    classDef done stroke:#16a34a,fill:#dcfce7,color:#14532d,stroke-width:2px
    classDef active stroke:#2563eb,fill:#eff6ff,color:#1e3a8a,stroke-width:2px
    classDef verify stroke:#7c3aed,fill:#f5f3ff,color:#4c1d95,stroke-width:2px
    classDef ready stroke:#0891b2,fill:#ecfeff,color:#164e63,stroke-width:2px
    classDef planned stroke:#0891b2,fill:#ecfeff,color:#164e63,stroke-width:2px
    classDef blocked stroke:#b45309,fill:#fffbeb,color:#78350f,stroke-width:2px
    classDef cancelled stroke:#6b7280,fill:#f9fafb,color:#374151,stroke-width:2px
    classDef superseded stroke:#6b7280,fill:#f9fafb,color:#374151,stroke-width:2px

Canonical record: .ai/repo/project/milestones/the-mesh-works-out-of-the-box.yaml. Read it back with majordomus plan show the-mesh-works-out-of-the-box.