peers.announce

{
  "additionalProperties": false,
  "description": "The input of `peers.announce`: what the calling peer is working on.",
  "properties": {
    "claim": {
      "description": "Which of this peer's claims this is, when the peer holds more than one.\n\nOne MCP session is not always one piece of work — a client that fans work out to\nsubagents shares its session with all of them — and without a name every\nannouncement replaces the last, so the board ends up describing whichever worker\nspoke most recently and the rest of the scope silently stops being claimed. Name a\nclaim and it stands beside the others; announce under that name again and it is\nupdated. Leave it out and this is the peer's one unnamed claim, which is what a\nsingle session announcing about itself wants.",
      "type": [
        "string",
        "null"
      ]
    },
    "intent": {
      "description": "One line, in the peer's words: the task, the question, the intent.",
      "type": "string"
    },
    "scope": {
      "default": [],
      "description": "Repository-relative paths the peer expects to touch. Informational: other peers\nread it to avoid a collision; nothing here enforces it.",
      "items": {
        "type": "string"
      },
      "type": "array"
    }
  },
  "required": [
    "intent"
  ],
  "title": "AnnounceInput",
  "type": "object"
}

{
  "$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"
    },
    "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"
    },
    "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"
    },
    "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": "What `announce` answers: the peer as recorded, and who else is on that ground.",
  "properties": {
    "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"
    },
    "overlaps": {
      "description": "Every other peer whose claimed scope meets this one. Empty is the ordinary case.",
      "items": {
        "$ref": "#/$defs/Overlap"
      },
      "type": "array"
    },
    "released": {
      "description": "Paths the claim this one replaced had, and this one does not.\n\nAnnouncing under a name a peer already used replaces that claim, which is what an\nupdate is. When the replacement is narrower, the peer has just stopped claiming\nground it held a moment ago, and the other peers stop being warned off it. That is\noccasionally what was meant and is otherwise a mistake nobody would ever see, so it\nis said here, at the moment it happens, rather than left to be discovered in a\ncollision later. Empty is the ordinary case.",
      "items": {
        "type": "string"
      },
      "type": "array"
    },
    "transport": {
      "$ref": "#/$defs/Transport",
      "description": "How it is attached."
    }
  },
  "required": [
    "id",
    "client",
    "transport",
    "connected_at",
    "last_seen_seconds_ago",
    "attached"
  ],
  "title": "Announced",
  "type": "object"
}