HTTP API: brief

What surrounds one working session, in one line and in a few: its episode and task, the peers of every board, the mesh, the integration queue and the derive queue, each section asked of its owner once and saying whether it could be read. The answer a session reports on itself from without being asked, and the one a provider mod shows as its status line (ADR 0136). Writes nothing.

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.

brief

GET /api/v1/brief brief.session

The session brief

One line and a few: this session's episode and task (the one the given provider session owns, else the pointer's), the peers of every board with the boards that could not be read named, the mesh's links and what its journal addresses to this runtime, the integration queue as `majordomus prs brief` says it, and the machine's derive lock. Composed by the server holding this checkout's lease, which holds the board and the mesh: the command line asks it and composes the brief itself only when none answers, saying so; a superseded server says its own board is unreachable by the repository's gather. Carries the reporting interval the policy declares (`session.brief_interval_minutes`) and the keep-awake text a session is told at its start. Writes nothing.

query
behaviorally_verified
benchmark required
cache disabled
MCP tool majordomus_brief
$ brief

Query parameters

name	type	required	description	examples
session	string	no	The provider's own session identity (Claude Code's session id): the brief names the open episode that session owns. Absent, the episode the pointer resolves to.	default: "00000000-0000-0000-0000-000000000000"
checkouts	Checkouts	no	Which checkouts the peers section covers: `repository` (every board, the default) or `this`.	default: "this"
local	boolean	no	Compose in the process that answers and never ask the checkout's leaseholder: what a forwarded request says, so that it is never forwarded again.	default: true

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/brief?session=00000000-0000-0000-0000-000000000000&checkouts=this&local=true"

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	SessionBrief	The session brief: 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.

BriefDeriveSection

object

The machine's derive queue: its lock and its priority marker (lib/machine_lock.sh).

property	type	required	description
state	BriefSectionState → BriefSectionState	yes	`undeclared` when the repository ships no derive lock.
holder	string \| null	no	The lock's owner line, when the lock is held.
pid	integer \| null	no	The holder's process id, when its line names one.
alive	boolean \| null	no	Whether that process is running on this machine.
held_seconds	integer \| null	no	Seconds since the lock was taken.
priority	string \| null	no	The branches the priority marker names, when it is present.
summary	string	yes	The section in words.

Used by SessionBrief

BriefIntegrationSection

object

The integration queue, as majordomus prs brief says it.

property	type	required	description
state	BriefSectionState → BriefSectionState	yes	Whether this checkout ever observed the forge.
summary	string	yes	The section in words.

Used by SessionBrief

BriefMeshSection

object

The mesh: the links of this runtime and what the journal addresses to it.

property	type	required	description
state	BriefSectionState → BriefSectionState	yes	Whether cooperation could be read.
active	boolean	yes	Whether cooperation runs in the composing process.
reason	string \| null	no	Why it does not, when it does not.
links	integer (uint)	yes	Links to other runtimes.
connected	integer (uint)	yes	Of them, connected.
failing	integer (uint)	yes	Of them, degraded, unreachable or expired.
claims_held	integer (uint)	yes	Claims held across the mesh.
own_claims	integer (uint)	yes	Of them, held by this runtime.
reviews_for_you	integer (uint)	yes	Open review requests that name this runtime as the reviewer.
handovers_waiting	integer (uint)	yes	Handovers another runtime published that nobody has consumed.
overlaps_for_you	integer (uint)	yes	Overlaps between a claim of this runtime and another's.
summary	string	yes	The section in words.

Used by SessionBrief

BriefOrigin

object

Which process composed the brief, and why that one.

property	type	required	description
process	string	yes	`leaseholder` (the server this checkout's lease names), `superseded` (a server that lost the lease), or `this_process` (no server answered, or the call asked for `local`).
url	string \| null	no	The address of the server that composed it, when one did.
note	string \| null	no	Why this process and not the leaseholder, when it is not the leaseholder.

Used by SessionBrief

BriefPeersSection

object

The workers of this repository, from every board the brief could read.

property	type	required	description
state	BriefSectionState → BriefSectionState	yes	Whether every board could be read.
attached	integer (uint)	yes	Attached peers across the boards read, the caller included.
boards	integer (uint)	yes	How many boards the answer covers.
unread	array of string	no	Every board that could not be read, as `<worktree>: <reason>`.
overlaps	integer (uint)	yes	Pairs of peers whose claimed scopes meet.
superseded	string \| null	no	Set when the composing server is superseded: its own board is unreachable by the repository's gather.
named	array of string	yes	The attached peers, one short line each, at most a bounded number.
summary	string	yes	The section in words.

Used by SessionBrief

BriefSectionState

"read" | "partial" | "unread" | "undeclared"

Whether a section of the brief could be read.

readIts owner answered in full.
partialIts owner answered, and part of what it covers could not be asked; the summary says which.
unreadIts owner did not answer; the summary says why.
undeclaredThe repository declares nothing for it (no derive lock, a mesh switched off).

Used by BriefDeriveSection BriefIntegrationSection BriefMeshSection BriefPeersSection BriefSessionSection

BriefSessionSection

object

The session the brief is about.

property	type	required	description
state	BriefSectionState → BriefSectionState	yes	Whether it could be read.
episode	string \| null	no	The open episode, when one is found.
provider_session	string \| null	no	The provider session that owns it.
branch	string	yes	The checkout's branch.
head	string	yes	The checkout's head, abbreviated.
task_id	string \| null	no	The active task's id, when one is active.
task	string \| null	no	The active task's words.
caller	string \| null	no	The calling MCP session's place on this board, when the call came through one.
summary	string	yes	The section in words.

Used by SessionBrief

SessionBrief

object

The answer of brief.session: what surrounds one session, in one line and in a few.

property	type	required	description
at	string	yes	When it was composed, RFC 3339.
line	string	yes	The brief in one line: the status line's text.
lines	array of string	yes	The brief in a few lines: one per section, then the peers it names.
interval_minutes	integer (uint64)	yes	How often a session reports on itself, in minutes (`session.brief_interval_minutes`).
keep_awake	string	yes	What a session is told at its start about keeping itself awake.
answered_by	BriefOrigin → BriefOrigin	yes	Which process composed it.
session	BriefSessionSection → BriefSessionSection	yes	This session: its episode and task.
peers	BriefPeersSection → BriefPeersSection	yes	The workers of every board.
mesh	BriefMeshSection → BriefMeshSection	yes	The mesh.
integration	BriefIntegrationSection → BriefIntegrationSection	yes	The integration queue.
derive	BriefDeriveSection → BriefDeriveSection	yes	The derive queue.

Used by brief.session