peers.list
Every worker of this repository: id, the client's own name and version from its initialize, transport, when it attached, when it was last seen, what it announced, and which checkout it is attached to. A server serves one checkout, so the board of a repository worked on through linked worktrees is gathered: this checkout's board out of memory, every other checkout's from the server its lease names, asked for its own board alone. 'covered' says how many checkouts were covered, 'boards' lists each one with a server, a worker or a board that could not be read (the rest counted in 'omitted'; 'view: full' lists every one), and 'complete' whether every board could be read, so a short board is never mistaken for an empty repository. 'checkouts: this' reads one board and enumerates, probes and asks nothing else. In-memory on every server; gone with the processes.
Every worker of this repository: id, the client's own name and version from its initialize, transport, when it attached, when it was last seen, what it announced, and which checkout it is attached to. A server serves one checkout, so the board of a repository worked on through linked worktrees is gathered: this checkout's board out of memory, every other checkout's from the server its lease names, asked for its own board alone. 'covered' says how many checkouts were covered, 'boards' lists each one with a server, a worker or a board that could not be read (the rest counted in 'omitted'; 'view: full' lists every one), and 'complete' whether every board could be read, so a short board is never mistaken for an empty repository. 'checkouts: this' reads one board and enumerates, probes and asks nothing else. In-memory on every server; gone with the processes.
- query
- behaviorally_verified
- module peers
- #peers
- #coordination
Exposure
Where this one definition is reachable. Absence is explicit: a surface not listed does not carry it.
| surface | as |
|---|---|
| MCP | tool majordomus_peers |
| HTTP | GET /api/v1/peers operationId peers.list |
| command line | — |
Schemas
The canonical input and output, from the Rust types; the MCP tool schema and the OpenAPI parameters and responses are derived from these.
input · PeerListInput
What to ask of
peers.list: how wide the board is.
The same one field, the same word and the same default as
super::server::ServerStatusInput, because it is the same question asked of the same
set of checkouts, and a caller should not have to learn it twice.
The evidence for that is the_default_board_is_the_repositorys below rather than a doc
example here: this module is pub(crate), so a doc test — which compiles as an external
crate — cannot name the type at all.
| property | type | required | description |
|---|---|---|---|
| checkouts | reference | no | Which checkouts the board covers. Absent means repository; this is the checkout the call reached and nothing else, and it is what a sibling server is asked so that a gather can never ask back. default "repository" |
| view | reference | no | How many of the covered checkouts are listed in boards. Absent means summary: every checkout with a server, a worker, or a board that could not be read, the rest counted in omitted; full lists every one. default "summary" |
JSON Schema
{
"$defs": {
"Checkouts": {
"description": "Which checkouts a reading of the server status covers.\n\nThe two answers cost differently and that is the whole reason the choice exists: the\nrepository's checkouts are read from git's registry of them and each one costs a lease\nread and a probe, while this checkout alone costs one of each and enumerates nothing.\nThe word each variant serialises to is the word the query parameter, the tool input and\nthe command-line flag all take.\n\n```\nuse majordomus_cli::capability::builtin::server::Checkouts;\nassert_eq!(serde_json::to_value(Checkouts::This).unwrap(), \"this\");\nassert_eq!(serde_json::to_value(Checkouts::Repository).unwrap(), \"repository\");\nassert_eq!(Checkouts::default(), Checkouts::Repository, \"the wide answer is what a caller who says nothing has always got\");\n```",
"oneOf": [
{
"const": "repository",
"description": "Every checkout git registers for the repository, the primary first — a lease read\nand a probe each. The default, because it is the answer this capability gave before\nthere was anything to ask.",
"type": "string"
},
{
"const": "this",
"description": "This checkout alone. No other checkout is enumerated, no other lease is read and no\nother server is probed; `servers` holds the one entry, and it is this one.",
"type": "string"
}
]
},
"PeerListView": {
"description": "How many of the covered checkouts `peers.list` lists one by one — the same two words, and\nthe same default, as the mesh's own `view` (`mesh::page::View`), for the same reason.\n\nOn 2026-10-22 this repository registered 625 checkouts, 601 of them with no server and\nnobody attached, and the default answer was 168 kB: past what an MCP client shows, so\nthe read every worker is told to make before it starts went through a saved file. A\ncheckout with no server holds no board (`ServerStanding::Absent`, or a `Stale` lease that\nnames a process that is gone), so listing it says only that it exists; the summary counts\nthose by standing and lists every other. The evidence is\n`the_summary_counts_only_checkouts_that_hold_no_board` below.",
"oneOf": [
{
"const": "summary",
"description": "This checkout, every checkout with a worker attached or a server standing, and every\nboard that could not be read; the checkouts with no server and nobody attached are\ncounted in `omitted` by standing.",
"type": "string"
},
{
"const": "full",
"description": "Every covered checkout, one entry each.",
"type": "string"
}
]
}
},
"description": "What to ask of `peers.list`: how wide the board is.\n\nThe same one field, the same word and the same default as\n`super::server::ServerStatusInput`, because it is the same question asked of the same\nset of checkouts, and a caller should not have to learn it twice.\n\nThe evidence for that is `the_default_board_is_the_repositorys` below rather than a doc\nexample here: this module is `pub(crate)`, so a doc test — which compiles as an external\ncrate — cannot name the type at all.",
"properties": {
"checkouts": {
"$ref": "#/$defs/Checkouts",
"default": "repository",
"description": "Which checkouts the board covers. Absent means `repository`; `this` is the checkout the call reached and nothing else, and it is what a sibling server is asked so that a gather can never ask back."
},
"view": {
"$ref": "#/$defs/PeerListView",
"default": "summary",
"description": "How many of the covered checkouts are listed in `boards`. Absent means `summary`: every checkout with a server, a worker, or a board that could not be read, the rest counted in `omitted`; `full` lists every one."
}
},
"title": "PeerListInput",
"type": "object"
}output · PeerList
The answer of
peers.list: every worker of this repository, from every checkout's board.| property | type | required | description |
|---|---|---|---|
| boards | array | yes | One entry per checkout the answer lists, reached or not: every covered checkout under
view: full; under the default summary, every one but those omitted counts. A board
that could not be read is always listed. |
| caller | one of 2 | no | The caller's own peer id, when the call came through an MCP session. A position on
this checkout's board, not a durable identity: it is handed out again after a
reconnect, and Peer::checkout is the half of a worker's identity that is not. |
| complete | boolean | yes | Whether every board the answer covers was read. false when a checkout's server
could not be asked, and BoardView::reason says which and why — so that "nobody
else is here" is never reported when the truth is "I could not ask". |
| count | integer | yes | How many peers are attached across every board that was read, the caller included. |
| covered | integer | yes | How many checkouts the answer covers, listed in boards or counted in omitted — a
count, where the input checkouts is a choice of which to cover. |
| omitted | object | no | The covered checkouts the summary does not list, counted by standing (absent,
stale): no server, nobody attached, no board. Empty under view: full. |
| overlaps | array | no | Every pair of peers whose claimed scope meets, each pair once — now across checkouts as well as within one. Empty is the ordinary case, and a reader who sees an entry here is looking at two workers about to do the same work. |
| peers | array | yes | The peers, this checkout's board first and then the siblings in the order git
registers them, each in its own board's attachment order. Every one carries the
checkout it belongs to, because p1 is the first session of every board. A peer
that announced something and then went away is still here, with attached: false. |
| stream | string | null | no | The mesh stream of the server that answered, when its mesh runs: the stream its own
board's peers are projected into. A sibling's answer carries it so that the gatherer
can name it on that sibling's BoardView. |
JSON Schema
{
"$defs": {
"Announcement": {
"description": "One claim a peer has made: what it is working on, and where.\n\nA peer may hold several. The `name` is what tells them apart and what makes announcing\nagain an update rather than a second claim: announce under the same name and the claim\nis replaced, announce under a new one and the peer now holds both. A peer that never\nnames anything holds exactly one claim, the unnamed one, which is what a single session\nannouncing about itself has always had.",
"properties": {
"at": {
"description": "When it was announced, RFC 3339, UTC.",
"type": "string"
},
"intent": {
"description": "One line: the task or intent, in the peer's words.",
"type": "string"
},
"name": {
"description": "What this claim is called, when the peer named it. Absent for a peer's unnamed claim.",
"type": [
"string",
"null"
]
},
"scope": {
"description": "Repository-relative paths the peer expects to touch; informational, never enforced here.",
"items": {
"type": "string"
},
"type": "array"
}
},
"required": [
"intent",
"scope",
"at"
],
"type": "object"
},
"BoardView": {
"description": "One checkout's board, as the gather found it.\n\nPresent for every checkout the answer covers, whether or not its board could be read,\nbecause a listing that silently drops the checkouts it could not reach is the shape of\nanswer that made this capability wrong in the first place: a reader would see a short\nboard and conclude nobody else is working here.",
"properties": {
"attached": {
"description": "How many of this board's peers are attached.",
"format": "uint",
"minimum": 0,
"type": "integer"
},
"branch": {
"description": "The branch checked out there, when it could be read.",
"type": [
"string",
"null"
]
},
"id": {
"description": "The checkout's identity digest, the same value `server.status` reports as\n`checkout_id`. One per checkout, never a path, and stable across a restart.",
"type": "string"
},
"reason": {
"description": "Why this board is not in the answer. `None` when it is.",
"type": [
"string",
"null"
]
},
"standing": {
"$ref": "#/$defs/ServerStanding",
"description": "Where its server stands, by the same reading `server.status` reports."
},
"stream": {
"description": "The mesh stream of the server whose memory holds this board, when its mesh runs: the\nstream it projects the board's peers into as `board-pN` sessions. A position such as\n`p1` is that server's alone, so only this stream ties a board peer to its session.",
"type": [
"string",
"null"
]
},
"this_checkout": {
"description": "Whether this is the checkout of the server answering the call.",
"type": "boolean"
},
"url": {
"description": "The address its lease names, when it has one.",
"type": [
"string",
"null"
]
},
"worktree": {
"description": "Where the checkout is. The one thing on this board that a human can act on\ndirectly, and the one thing that survives a reconnect.",
"type": "string"
}
},
"required": [
"id",
"worktree",
"this_checkout",
"standing",
"attached"
],
"type": "object"
},
"ClientInfo": {
"description": "What a client said about itself in `initialize`.",
"properties": {
"name": {
"description": "`clientInfo.name`: `claude-code`, `codex`, `gemini-cli`, whatever the client sends.",
"type": "string"
},
"title": {
"description": "`clientInfo.title`, when the client sends one.",
"type": [
"string",
"null"
]
},
"version": {
"description": "`clientInfo.version`.",
"type": "string"
}
},
"required": [
"name",
"version"
],
"type": "object"
},
"Overlap": {
"description": "Two peers that claimed the same ground.\n\nReported when the second of them announces, so that a collision is known at the moment\nit is created rather than discovered afterwards in the history of a branch.",
"properties": {
"attached": {
"description": "Whether that peer is still attached. An overlap with a departed peer is a weaker\nsignal than one with a live session, and the reader is told which it is.",
"type": "boolean"
},
"checkout": {
"anyOf": [
{
"$ref": "#/$defs/PeerCheckout"
},
{
"type": "null"
}
],
"description": "Which checkout the other peer is attached to, when the reader knew.\n\nThe overlap that matters most is the one nobody could see before: two workers in\ntwo worktrees of one repository, each reading a board that held only itself, both\nclaiming `apps/majordomus-cli/src`. Naming the checkout is what turns \"p1 is on\nyour ground\" into something a reader can act on when `p1` is not on this board."
},
"intent": {
"description": "What it said it was doing.",
"type": "string"
},
"paths": {
"description": "The claims that meet: one line per pair, `yours` and `theirs`.",
"items": {
"$ref": "#/$defs/OverlapPath"
},
"type": "array"
},
"peer": {
"$ref": "#/$defs/PeerId",
"description": "The other peer."
}
},
"required": [
"peer",
"attached",
"intent",
"paths"
],
"type": "object"
},
"OverlapPath": {
"description": "One pair of claims that contain one another.",
"properties": {
"theirs": {
"description": "The path the other peer claimed.",
"type": "string"
},
"yours": {
"description": "The path the announcing peer claimed.",
"type": "string"
}
},
"required": [
"yours",
"theirs"
],
"type": "object"
},
"Peer": {
"description": "One peer as the board lists it.",
"properties": {
"address": {
"anyOf": [
{
"$ref": "#/$defs/PeerAddress"
},
{
"type": "null"
}
],
"description": "Where the worker behind this peer can be reached from outside its connection: its\nmachine, its process, its provider session and the socket other sessions message it\non; see `PeerAddress`. Derived when the peer attached, never announced by hand.\nAbsent for a client that exposes none of it."
},
"announcement": {
"anyOf": [
{
"$ref": "#/$defs/Announcement"
},
{
"type": "null"
}
],
"description": "The most recently made of `Peer::claims`, for a reader that wants one line rather\nthan all of them. Derived from `claims` and never a second account of it: a peer\nholding one claim reports the same thing in both, which is what every peer that does\nnot name its claims reports."
},
"attached": {
"description": "Whether the session is still attached. A peer that announced something and then\nwent away is kept and listed with `attached: false`: what it said it was working on\noutlives the connection that said it, because the work does.",
"type": "boolean"
},
"checkout": {
"anyOf": [
{
"$ref": "#/$defs/PeerCheckout"
},
{
"type": "null"
}
],
"description": "Which checkout of the repository this peer is attached to; see `PeerCheckout`.\n\nThe board itself never sets it — a board does not know where it is — and it is\nstamped by the reader that gathered this peer, which is the one thing that knows\nwhich checkout's server it asked."
},
"claims": {
"description": "Every claim this peer holds, in name order, the unnamed one first. Empty for a peer\nthat has announced nothing.\n\nOne connection may be doing several things at once — a session that fans work out to\nsubagents shares its MCP session with all of them — and before this field the board\ncould hold only the last thing said, so each announcement silently erased the one\nbefore it and the other peers stopped seeing the rest of the scope.",
"items": {
"$ref": "#/$defs/Announcement"
},
"type": "array"
},
"client": {
"$ref": "#/$defs/ClientInfo",
"description": "The client behind it."
},
"connected_at": {
"description": "When it attached, RFC 3339, UTC.",
"type": "string"
},
"id": {
"$ref": "#/$defs/PeerId",
"description": "`p1`, `p2`, ..."
},
"last_seen_seconds_ago": {
"description": "Seconds since its last message.",
"format": "uint64",
"minimum": 0,
"type": "integer"
},
"transport": {
"$ref": "#/$defs/Transport",
"description": "How it is attached."
}
},
"required": [
"id",
"client",
"transport",
"connected_at",
"last_seen_seconds_ago",
"attached"
],
"type": "object"
},
"PeerAddress": {
"description": "Where the worker behind a peer can be reached from outside its MCP connection.\n\nA board row named a client and a version, and nothing a person or another session could\nact on: on 2026-10-22 the session running a 33-minute remote `cargo test --doc` could be\nfound only by walking an ssh client's parent chain to a provider pid, its messaging\nsocket, and a start time matched by hand. Every one of those facts is in the environment\nthe provider hands the processes it starts — the MCP server among them — so the address\nis read from there when the peer attaches, and never asked of the model.\n\nThe provider's messaging *token* is a credential and is never read: the address is where\nto knock, not the key.\n\n```\nuse majordomus_cli::peers::PeerAddress;\n// a client that exposes nothing still has a machine and a parent process\nlet bare = PeerAddress::from_env(|_| None, Some(4242), \"lundra\").unwrap();\nassert_eq!((bare.host.as_str(), bare.pid), (\"lundra\", Some(4242)));\nassert!(bare.provider.is_none() && bare.mesh_session().is_none());\n```",
"properties": {
"host": {
"description": "The machine the worker runs on.",
"type": "string"
},
"pid": {
"description": "The worker's own process: the provider's pid, not the MCP bridge it started.",
"format": "uint32",
"minimum": 0,
"type": [
"integer",
"null"
]
},
"provider": {
"description": "The provider whose session this is (`claude-code`), when its environment says so.",
"type": [
"string",
"null"
]
},
"session": {
"description": "The provider's id for the session, the one its lifecycle hooks are given.",
"type": [
"string",
"null"
]
},
"socket": {
"description": "The socket other sessions on the same machine message this one through.",
"type": [
"string",
"null"
]
}
},
"required": [
"host"
],
"type": "object"
},
"PeerCheckout": {
"description": "Which checkout of the repository a peer is attached to.\n\nA board is one process's memory and a server serves one checkout, so a peer read from\na sibling checkout's server and a peer of this one are otherwise indistinguishable —\nand worse than indistinguishable, because the ids collide: `p1` is the first session\nof *every* board, so a repository-wide listing without this field would hold several\npeers called `p1` and no way to tell them apart. This is the qualification. The\nworktree path is the durable half of a worker's identity: the peer id is a position on\none board and is handed out again after a reconnect (`p3` this morning, `p1` after the\nbridge re-attached), while the checkout a worker is working in outlives its connection.\n\nAbsent on a peer a server reports about its own board without being asked which\ncheckout that is — `peers.announce` answers about the announcing session and the\nanswer is this server's by construction. The repository-wide listing stamps every\npeer it gathers, its own included, so that no entry of that answer is unqualified.\n\n```\nuse majordomus_cli::peers::PeerCheckout;\nlet c = PeerCheckout {\n id: \"b8293f11\".into(),\n worktree: \"/repo-wt/feature/x\".into(),\n branch: Some(\"feature/x\".into()),\n this_checkout: false,\n};\nlet v = serde_json::to_value(&c).unwrap();\nassert_eq!(v[\"branch\"], \"feature/x\");\nassert_eq!(v[\"this_checkout\"], false);\n```",
"properties": {
"branch": {
"description": "The branch checked out there, when it could be read.",
"type": [
"string",
"null"
]
},
"id": {
"description": "The checkout's identity digest, the same value `server.status` reports as\n`checkout_id`. One per checkout, never a path, and stable across a restart.",
"type": "string"
},
"this_checkout": {
"description": "Whether this is the checkout of the server answering the call.",
"type": "boolean"
},
"worktree": {
"description": "Where the checkout is. The one thing on this board that a human can act on\ndirectly, and the one thing that survives a reconnect.",
"type": "string"
}
},
"required": [
"id",
"worktree",
"this_checkout"
],
"type": "object"
},
"PeerId": {
"description": "A peer's identity for the life of the server: `p1`, `p2`, ... in attachment order.\n`p1` is the session that started the server.",
"type": "string"
},
"ServerStanding": {
"description": "Where a checkout's server stands, decided from its lease, whether the server the lease\nnames answers for that checkout, and whether what answers is this executable's code.\n\n```\nuse majordomus_cli::capability::builtin::server::ServerStanding;\nlet all = [ServerStanding::Absent, ServerStanding::Starting, ServerStanding::Ready,\n ServerStanding::Outdated, ServerStanding::Stale];\nlet words: Vec<&str> = all.iter().map(|s| s.as_str()).collect();\nassert_eq!(words, [\"absent\", \"starting\", \"ready\", \"outdated\", \"stale\"]);\nassert_eq!(serde_json::from_str::<ServerStanding>(\"\\\"stale\\\"\").unwrap(), ServerStanding::Stale);\n```",
"oneOf": [
{
"const": "absent",
"description": "No lease: nothing serves this checkout.",
"type": "string"
},
{
"const": "starting",
"description": "A lease without an address, young enough that its owner is still binding.",
"type": "string"
},
{
"const": "ready",
"description": "The server the lease names answers for this checkout, from the code on disk, at\nthis executable's version.",
"type": "string"
},
{
"const": "outdated",
"description": "The server answers, but from older code than this executable, or from a file that\nhas been replaced since it started: everything it says is yesterday's.",
"type": "string"
},
{
"const": "stale",
"description": "The lease names a server that does not answer, or is not a lease at all.",
"type": "string"
}
]
},
"Transport": {
"description": "How a peer reached the server.",
"oneOf": [
{
"const": "stdio",
"description": "The owner's own client, on the process's stdin and stdout.",
"type": "string"
},
{
"const": "http",
"description": "MCP over HTTP at `/mcp`: a `majordomus mcp` bridge, or a client speaking it directly.",
"type": "string"
}
]
}
},
"description": "The answer of `peers.list`: every worker of this repository, from every checkout's board.",
"properties": {
"boards": {
"description": "One entry per checkout the answer lists, reached or not: every covered checkout under\n`view: full`; under the default summary, every one but those `omitted` counts. A board\nthat could not be read is always listed.",
"items": {
"$ref": "#/$defs/BoardView"
},
"type": "array"
},
"caller": {
"anyOf": [
{
"$ref": "#/$defs/PeerId"
},
{
"type": "null"
}
],
"description": "The caller's own peer id, when the call came through an MCP session. A position on\nthis checkout's board, not a durable identity: it is handed out again after a\nreconnect, and `Peer::checkout` is the half of a worker's identity that is not."
},
"complete": {
"description": "Whether every board the answer covers was read. `false` when a checkout's server\ncould not be asked, and `BoardView::reason` says which and why — so that \"nobody\nelse is here\" is never reported when the truth is \"I could not ask\".",
"type": "boolean"
},
"count": {
"description": "How many peers are attached across every board that was read, the caller included.",
"format": "uint",
"minimum": 0,
"type": "integer"
},
"covered": {
"description": "How many checkouts the answer covers, listed in `boards` or counted in `omitted` — a\ncount, where the input `checkouts` is a choice of which to cover.",
"format": "uint",
"minimum": 0,
"type": "integer"
},
"omitted": {
"additionalProperties": {
"format": "uint",
"minimum": 0,
"type": "integer"
},
"description": "The covered checkouts the summary does not list, counted by standing (`absent`,\n`stale`): no server, nobody attached, no board. Empty under `view: full`.",
"type": "object"
},
"overlaps": {
"description": "Every pair of peers whose claimed scope meets, each pair once — now across\ncheckouts as well as within one. Empty is the ordinary case, and a reader who sees\nan entry here is looking at two workers about to do the same work.",
"items": {
"$ref": "#/$defs/Overlap"
},
"type": "array"
},
"peers": {
"description": "The peers, this checkout's board first and then the siblings in the order git\nregisters them, each in its own board's attachment order. Every one carries the\ncheckout it belongs to, because `p1` is the first session of every board. A peer\nthat announced something and then went away is still here, with `attached: false`.",
"items": {
"$ref": "#/$defs/Peer"
},
"type": "array"
},
"stream": {
"description": "The mesh stream of the server that answered, when its mesh runs: the stream its own\nboard's peers are projected into. A sibling's answer carries it so that the gatherer\ncan name it on that sibling's `BoardView`.",
"type": [
"string",
"null"
]
}
},
"required": [
"count",
"peers",
"covered",
"boards",
"complete"
],
"title": "PeerList",
"type": "object"
}Policies
- benchmark
- required — a target on every transport the exposure declares; the cases are the input type's
- cache
- disabled — every call runs the handler
Benchmark targets
Derived from the registry for this repository: one requirement per transport, and the cases the input type provides. The whole matrix is on the benchmarks page.
The moments this answers
- had two sessions writing into one checkout without either knowing Two workers in one working tree see each other only as unexplained file changes, and each treats the other as noise.
- could not say why one provider was used for that work and another for this Provider and model selection is made implicitly, per session, and recorded nowhere, so it cannot be reviewed or repeated.