HTTP API: blackboard

Who works on what in this repository, as one projection of the records that already know it: every checkout's board, the mesh journal's sessions, claims, reviews and handovers on every linked machine, and the monitor's newest signals, joined once so that no surface joins them again (ADR 0176). A board peer and a mesh session are one worker only when an explicit identifier joins them; a source that could not be read makes the answer incomplete and says why.

Rendered from docs/generated/openapi.json, which the executable generates from its capability registry and CI refuses stale. The raw document is at /openapi.json; a running server serves the same document at its own /openapi.json and Swagger UI at /swagger.

blackboard

GET /api/v1/blackboard blackboard.snapshot

Who works on what, now

Every worker of this repository — attached to a checkout's board or in an active mesh session on any linked machine — with the client it is, what it announced, its checkout, branch, machine and claims (advisory or exclusive); the claims that meet (potential, or confirmed when both are exclusive or the mesh marked one conflicted); the open reviews and untaken handovers; typed relations between workers, verified only when an explicit identifier joins them; the newest signals with the monitor's cursor a follower resumes from; each source with how it was read, and whether the answer is complete. Reads only.

query
experimental
benchmark required
cache disabled
MCP tool majordomus_blackboard
$ blackboard

Query parameters

name	type	required	description	examples
checkouts	Checkouts	no	Which checkouts' boards it covers: `repository` (every one, the default) or `this`.	addressed: "this"this-checkout: "this"
for	string	no	Comma-separated names of the reader — a worker (`1b`), a role, a login — so that the signals addressed to it are marked `for_you`. An MCP caller is also its own board session.	addressed: "1b"
signals	integer (uint64)	no	How many of the newest signals of the last hour it carries (default 30, at most 200); 0 reads no signals at all, for a follower that reads them by its own cursor.	addressed: 10
sources	string	no	A comma-separated subset of the monitor's sources, `mesh`, `executor` and `github` (default: `mesh,executor`).	addressed: "mesh"this-checkout: "mesh,executor"

Try it

The port is whatever the server logged; 8741 is the one it asks for first. The values are the operation's first example.

curl -s "http://127.0.0.1:8741/api/v1/blackboard?checkouts=this&for=1b&signals=10&sources=mesh"

Tested by apps/majordomus-cli/tests/http_serve.rs, which replays the route with these values against a server on a real socket.

Responses

status	body	meaning
200	Blackboard	Who works on what, now: the result.
400	ErrorBody	`invalid_input`: The input does not fit the schema: a parameter of the wrong type, an unknown one, or a value the capability rejects.
404	ErrorBody	`not_found`: The input names something the repository does not hold.
500	ErrorBody	`internal`: The capability failed for a reason of its own; the message names it.
default	ErrorBody	Any other failure the transport reports: 405 `method_not_allowed` for another method on this path, 400 `invalid_input` for a body that is not a JSON object.

Schemas

The components only this tag's operations use. Each row is the type's own field, its doc comment the description; a type another page owns links there.

Blackboard

object

The answer of blackboard.snapshot: who works on what in this repository, on every board and every linked machine, with what meets and what waits, read once from the records that know it.

property	type	required	description
at	string	yes	When it was read (RFC 3339).
checkout	string	yes	The identity of the checkout whose server answered.
head	string \| null	no	That checkout's HEAD, when it has one.
complete	boolean	yes	Whether every board was read and the mesh, when the repository declares one, could be asked. `false` names its reason in `sources`, so that "nobody is here" is never what "I could not ask" reads as. The monitor's sources are reported in `sources` with their state and do not decide it: an empty executor trail or an absent `gh` is no board that could not be read.
sources	array of BlackboardSource → BlackboardSource	yes	Each source and how it was read.
boards	array of BoardView → BoardView	yes	Each checkout's board the summary lists: reached or not, with a server or a worker.
covered	integer (uint)	yes	How many checkouts the answer covers, listed in `boards` or counted in `omitted`.
omitted	map of integer (uint)	no	The covered checkouts `boards` does not list, counted by standing (`absent`, `stale`): no server, nobody attached, no board.
present	integer (uint)	yes	How many workers are here now: attached to a board or in an active mesh session.
workers	array of BlackboardWorker → BlackboardWorker	yes	Every worker, this checkout's board first, then the other boards, then the mesh.
conflicts	array of BlackboardConflict → BlackboardConflict	yes	The claims that meet, at most a hundred, confirmed first.
conflicts_total	integer (uint)	yes	How many conflicts there are in all.
reviews	array of BlackboardReview → BlackboardReview	yes	The review requests nobody has answered, at most fifty.
handovers	array of BlackboardHandover → BlackboardHandover	yes	The handovers nobody has taken, at most fifty.
relations	array of BlackboardRelation → BlackboardRelation	yes	The typed relations between workers.
signals	array of MonitorSignal → MonitorSignal	yes	The newest signals of the last hour, oldest first.
for_you	integer (uint)	yes	How many of them are for the reader.
cursor	string	yes	The monitor's cursor after these signals: where a follower resumes.

Used by blackboard.snapshot

BlackboardCertainty

"potential" | "confirmed"

How sure a conflict is.

potentialTwo claims meet and at least one of them is advisory: two workers about to touch the same paths, told and not stopped.
confirmedTwo exclusive claims meet, or the mesh marked one conflicted: what an exclusive claim exists to prevent has happened.

Used by BlackboardConflict

BlackboardClaim

object

One claim a worker holds.

property	type	required	description
name	string \| null	no	The claim's name, when its worker holds several.
intent	string \| null	no	What it is for, in the worker's words.
scope	array of string	yes	The repository paths it names.
mode	ClaimMode → ClaimMode	yes	`advisory` (an announcement: overlaps are reported) or `exclusive` (a second exclusive claim meeting it is refused while it lives). A board announcement is advisory.
issue	string \| null	no	The issue it is for, when the claim names one.
record	string \| null	no	The mesh claim's key, when it is a journal record; a board announcement has none.
conflicted	boolean	no	Whether the mesh found it conflicting with another live claim.

Used by BlackboardWorker

BlackboardClaimRef

object

One side of a conflict: a worker and which of its claims.

property	type	required	description
worker	string	yes	The worker's key.
claim	string \| null	no	The claim's name, when it has one.
record	string \| null	no	The mesh claim's key, when it is a journal record.

Used by BlackboardConflict

BlackboardConflict

object

Two claims of two different workers whose scopes meet.

property	type	required	description
certainty	BlackboardCertainty → BlackboardCertainty	yes	Potential or confirmed.
first	BlackboardClaimRef → BlackboardClaimRef	yes	The claim that came first in the answer's order.
second	BlackboardClaimRef → BlackboardClaimRef	yes	The claim that meets it.
paths	array of OverlapPath → OverlapPath	yes	The paths that meet, `yours` the first's and `theirs` the second's.

Used by Blackboard

BlackboardEvidence

"verified" | "candidate"

What a relation rests on.

verifiedAn explicit identifier or a journal record joins the two ends.
candidateThe ends could be joined and nothing proves it: more than one record fits.

Used by BlackboardRelation

BlackboardHandover

object

A handover published to the mesh that nobody has taken. Its body is not repeated here: mesh.state holds it. The journal names no recipient for a handover — whoever takes it is its addressee — so none is inferred here.

property	type	required	description
id	string	yes	The handover's id.
runtime	string	yes	The runtime that published it.
name	string \| null	no	Its name, when it has one.
branch	string \| null	no	The branch it continues.
issue	string \| null	no	The issue it continues.
task	string \| null	no	The task it continues.
created_at	string \| null	no	When it was written.

Used by Blackboard

BlackboardOrigin

"board" | "mesh"

Where a worker of the blackboard was found.

boardOn a checkout's board: an MCP client attached to that checkout's server.
meshIn the mesh journal only: a session no board of this repository holds — another machine's, a task's, or a client's own.

Used by BlackboardWorker

BlackboardPresence

"attached" | "departed" | "active"

Whether a worker is here now.

attachedAttached to its board now.
departedGone from its board, kept because it still holds an announcement.
activeAn open mesh session whose runtime still beats.

Used by BlackboardWorker

BlackboardRelation

object

A typed relation between two workers, or a worker and the addressee a record names.

property	type	required	description
kind	BlackboardRelationKind → BlackboardRelationKind	yes	What it is.
evidence	BlackboardEvidence → BlackboardEvidence	yes	What it rests on.
from	string	yes	A worker's key.
to	string	yes	A worker's key, or the addressee as the record names it when no worker is it.
record	string	yes	The record it rests on: a session or a review key.

Used by Blackboard

BlackboardRelationKind

"same_worker" | "review"

What a relation between two workers is.

same_workerA board peer and a mesh session that may be one worker.
reviewOne worker asked another for a review.

Used by BlackboardRelation

BlackboardReview

object

A review request nobody has answered.

property	type	required	description
key	string	yes	The review's key in the journal.
from	string	yes	The requesting worker's key, or its session key when no worker holds it.
subject	string	yes	What it asks about.
reviewer	string \| null	no	Whom it asks, as the request names it; absent means anyone.
issue	string \| null	no	The issue it names.

Used by Blackboard

BlackboardSource

object

One source of the blackboard and how it was read.

property	type	required	description
source	string	yes	`board`, `mesh`, or a monitor source as `monitor.<name>`.
state	BlackboardSourceState → BlackboardSourceState	yes	How it was read.
reason	string \| null	no	Why it is not `ok`.

Used by Blackboard

BlackboardSourceState

"ok" | "partial" | "absent" | "skipped"

How one source of the blackboard was read.

okRead whole.
partialRead, and some of what it covers could not be asked.
absentNot read; the reason says why.
skippedNot asked for.

Used by BlackboardSource

BlackboardWorker

object

One worker of the repository: a board peer, a mesh session, or one of each that an explicit identifier joins.

property	type	required	description
key	string	yes	Stable for as long as the worker is here: `board:<checkout>/<peer>` or `mesh:<stream>/<session>`. Never a bare peer id.
origin	BlackboardOrigin → BlackboardOrigin	yes	Where it was found.
presence	BlackboardPresence → BlackboardPresence	yes	Whether it is here now.
client	string	yes	The client's own name, from its MCP initialize or its mesh session.
title	string \| null	no	The client's display title or the worker it says it is, when it gave one.
version	string \| null	no	The client's version, from its initialize.
intent	string \| null	no	What it said it is doing; absent means it announced nothing.
checkout	string \| null	no	The checkout's identity.
worktree	string \| null	no	The checkout's path on its machine.
branch	string \| null	no	The branch it works on.
board_peer	string \| null	no	Its position on its board (`p3`): meaningful on that board only.
session	string \| null	no	Its mesh session's key, when it has one.
machine	string \| null	no	The machine's display name.
runtime	string \| null	no	The runtime (`<node>-<runtime>`) its mesh session belongs to.
task	string \| null	no	The task its mesh session names.
issue	string \| null	no	The issue its mesh session names.
connected_at	string \| null	no	When it attached to its board.
last_seen_seconds_ago	integer \| null	no	Seconds since its board last heard from it.
last_beat_ms	integer \| null	no	Milliseconds since its runtime last beat. A beat is liveness, not work done.
claims	array of BlackboardClaim → BlackboardClaim	no	Its claims, board announcements and live mesh claims alike.

Used by Blackboard