brief.session

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
module brief
#session
#peers
#coordination
#brief

Exposure

Where this one definition is reachable. Absence is explicit: a surface not listed does not carry it.

surface	as
MCP	tool majordomus_brief
HTTP	GET /api/v1/brief operationId brief.session
command line	majordomus brief

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 · BriefInput

What to ask of brief.session.

property	type	required	description
checkouts	reference	no	Which checkouts the peers section covers: `repository` (every board, the default) or `this`. default "repository"
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 false
session	string \| null	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.

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"
        }
      ]
    }
  },
  "description": "What to ask of `brief.session`.",
  "properties": {
    "checkouts": {
      "$ref": "#/$defs/Checkouts",
      "default": "repository",
      "description": "Which checkouts the peers section covers: `repository` (every board, the default) or `this`."
    },
    "local": {
      "default": false,
      "description": "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.",
      "type": "boolean"
    },
    "session": {
      "description": "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.",
      "type": [
        "string",
        "null"
      ]
    }
  },
  "title": "BriefInput",
  "type": "object"
}

output · SessionBrief

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

property	type	required	description
answered_by	reference	yes	Which process composed it.
at	string	yes	When it was composed, RFC 3339.
derive	reference	yes	The derive queue.
integration	reference	yes	The integration queue.
interval_minutes	integer	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.
line	string	yes	The brief in one line: the status line's text.
lines	array	yes	The brief in a few lines: one per section, then the peers it names.
mesh	reference	yes	The mesh.
peers	reference	yes	The workers of every board.
session	reference	yes	This session: its episode and task.

JSON Schema

{
  "$defs": {
    "BriefDeriveSection": {
      "description": "The machine's derive queue: its lock and its priority marker (`lib/machine_lock.sh`).",
      "properties": {
        "alive": {
          "description": "Whether that process is running on this machine.",
          "type": [
            "boolean",
            "null"
          ]
        },
        "held_seconds": {
          "description": "Seconds since the lock was taken.",
          "format": "uint64",
          "minimum": 0,
          "type": [
            "integer",
            "null"
          ]
        },
        "holder": {
          "description": "The lock's owner line, when the lock is held.",
          "type": [
            "string",
            "null"
          ]
        },
        "pid": {
          "description": "The holder's process id, when its line names one.",
          "format": "uint32",
          "minimum": 0,
          "type": [
            "integer",
            "null"
          ]
        },
        "priority": {
          "description": "The branches the priority marker names, when it is present.",
          "type": [
            "string",
            "null"
          ]
        },
        "state": {
          "$ref": "#/$defs/BriefSectionState",
          "description": "`undeclared` when the repository ships no derive lock."
        },
        "summary": {
          "description": "The section in words.",
          "type": "string"
        }
      },
      "required": [
        "state",
        "summary"
      ],
      "type": "object"
    },
    "BriefIntegrationSection": {
      "description": "The integration queue, as `majordomus prs brief` says it.",
      "properties": {
        "state": {
          "$ref": "#/$defs/BriefSectionState",
          "description": "Whether this checkout ever observed the forge."
        },
        "summary": {
          "description": "The section in words.",
          "type": "string"
        }
      },
      "required": [
        "state",
        "summary"
      ],
      "type": "object"
    },
    "BriefMeshSection": {
      "description": "The mesh: the links of this runtime and what the journal addresses to it.",
      "properties": {
        "active": {
          "description": "Whether cooperation runs in the composing process.",
          "type": "boolean"
        },
        "claims_held": {
          "description": "Claims held across the mesh.",
          "format": "uint",
          "minimum": 0,
          "type": "integer"
        },
        "connected": {
          "description": "Of them, connected.",
          "format": "uint",
          "minimum": 0,
          "type": "integer"
        },
        "failing": {
          "description": "Of them, degraded, unreachable or expired.",
          "format": "uint",
          "minimum": 0,
          "type": "integer"
        },
        "handovers_waiting": {
          "description": "Handovers another runtime published that nobody has consumed.",
          "format": "uint",
          "minimum": 0,
          "type": "integer"
        },
        "links": {
          "description": "Links to other runtimes.",
          "format": "uint",
          "minimum": 0,
          "type": "integer"
        },
        "overlaps_for_you": {
          "description": "Overlaps between a claim of this runtime and another's.",
          "format": "uint",
          "minimum": 0,
          "type": "integer"
        },
        "own_claims": {
          "description": "Of them, held by this runtime.",
          "format": "uint",
          "minimum": 0,
          "type": "integer"
        },
        "reason": {
          "description": "Why it does not, when it does not.",
          "type": [
            "string",
            "null"
          ]
        },
        "reviews_for_you": {
          "description": "Open review requests that name this runtime as the reviewer.",
          "format": "uint",
          "minimum": 0,
          "type": "integer"
        },
        "state": {
          "$ref": "#/$defs/BriefSectionState",
          "description": "Whether cooperation could be read."
        },
        "summary": {
          "description": "The section in words.",
          "type": "string"
        }
      },
      "required": [
        "state",
        "active",
        "links",
        "connected",
        "failing",
        "claims_held",
        "own_claims",
        "reviews_for_you",
        "handovers_waiting",
        "overlaps_for_you",
        "summary"
      ],
      "type": "object"
    },
    "BriefOrigin": {
      "description": "Which process composed the brief, and why that one.",
      "properties": {
        "note": {
          "description": "Why this process and not the leaseholder, when it is not the leaseholder.",
          "type": [
            "string",
            "null"
          ]
        },
        "process": {
          "description": "`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`).",
          "type": "string"
        },
        "url": {
          "description": "The address of the server that composed it, when one did.",
          "type": [
            "string",
            "null"
          ]
        }
      },
      "required": [
        "process"
      ],
      "type": "object"
    },
    "BriefPeersSection": {
      "description": "The workers of this repository, from every board the brief could read.",
      "properties": {
        "attached": {
          "description": "Attached peers across the boards read, the caller included.",
          "format": "uint",
          "minimum": 0,
          "type": "integer"
        },
        "boards": {
          "description": "How many boards the answer covers.",
          "format": "uint",
          "minimum": 0,
          "type": "integer"
        },
        "named": {
          "description": "The attached peers, one short line each, at most a bounded number.",
          "items": {
            "type": "string"
          },
          "type": "array"
        },
        "overlaps": {
          "description": "Pairs of peers whose claimed scopes meet.",
          "format": "uint",
          "minimum": 0,
          "type": "integer"
        },
        "state": {
          "$ref": "#/$defs/BriefSectionState",
          "description": "Whether every board could be read."
        },
        "summary": {
          "description": "The section in words.",
          "type": "string"
        },
        "superseded": {
          "description": "Set when the composing server is superseded: its own board is unreachable by the repository's gather.",
          "type": [
            "string",
            "null"
          ]
        },
        "unread": {
          "description": "Every board that could not be read, as `<worktree>: <reason>`.",
          "items": {
            "type": "string"
          },
          "type": "array"
        }
      },
      "required": [
        "state",
        "attached",
        "boards",
        "overlaps",
        "named",
        "summary"
      ],
      "type": "object"
    },
    "BriefSectionState": {
      "description": "Whether a section of the brief could be read.",
      "oneOf": [
        {
          "const": "read",
          "description": "Its owner answered in full.",
          "type": "string"
        },
        {
          "const": "partial",
          "description": "Its owner answered, and part of what it covers could not be asked; the summary says which.",
          "type": "string"
        },
        {
          "const": "unread",
          "description": "Its owner did not answer; the summary says why.",
          "type": "string"
        },
        {
          "const": "undeclared",
          "description": "The repository declares nothing for it (no derive lock, a mesh switched off).",
          "type": "string"
        }
      ]
    },
    "BriefSessionSection": {
      "description": "The session the brief is about.",
      "properties": {
        "branch": {
          "description": "The checkout's branch.",
          "type": "string"
        },
        "caller": {
          "description": "The calling MCP session's place on this board, when the call came through one.",
          "type": [
            "string",
            "null"
          ]
        },
        "episode": {
          "description": "The open episode, when one is found.",
          "type": [
            "string",
            "null"
          ]
        },
        "head": {
          "description": "The checkout's head, abbreviated.",
          "type": "string"
        },
        "provider_session": {
          "description": "The provider session that owns it.",
          "type": [
            "string",
            "null"
          ]
        },
        "state": {
          "$ref": "#/$defs/BriefSectionState",
          "description": "Whether it could be read."
        },
        "summary": {
          "description": "The section in words.",
          "type": "string"
        },
        "task": {
          "description": "The active task's words.",
          "type": [
            "string",
            "null"
          ]
        },
        "task_id": {
          "description": "The active task's id, when one is active.",
          "type": [
            "string",
            "null"
          ]
        }
      },
      "required": [
        "state",
        "branch",
        "head",
        "summary"
      ],
      "type": "object"
    }
  },
  "description": "The answer of `brief.session`: what surrounds one session, in one line and in a few.",
  "properties": {
    "answered_by": {
      "$ref": "#/$defs/BriefOrigin",
      "description": "Which process composed it."
    },
    "at": {
      "description": "When it was composed, RFC 3339.",
      "type": "string"
    },
    "derive": {
      "$ref": "#/$defs/BriefDeriveSection",
      "description": "The derive queue."
    },
    "integration": {
      "$ref": "#/$defs/BriefIntegrationSection",
      "description": "The integration queue."
    },
    "interval_minutes": {
      "description": "How often a session reports on itself, in minutes (`session.brief_interval_minutes`).",
      "format": "uint64",
      "minimum": 0,
      "type": "integer"
    },
    "keep_awake": {
      "description": "What a session is told at its start about keeping itself awake.",
      "type": "string"
    },
    "line": {
      "description": "The brief in one line: the status line's text.",
      "type": "string"
    },
    "lines": {
      "description": "The brief in a few lines: one per section, then the peers it names.",
      "items": {
        "type": "string"
      },
      "type": "array"
    },
    "mesh": {
      "$ref": "#/$defs/BriefMeshSection",
      "description": "The mesh."
    },
    "peers": {
      "$ref": "#/$defs/BriefPeersSection",
      "description": "The workers of every board."
    },
    "session": {
      "$ref": "#/$defs/BriefSessionSection",
      "description": "This session: its episode and task."
    }
  },
  "required": [
    "at",
    "line",
    "lines",
    "interval_minutes",
    "keep_awake",
    "answered_by",
    "session",
    "peers",
    "mesh",
    "integration",
    "derive"
  ],
  "title": "SessionBrief",
  "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.

transport	state	cases	targets
direct	covered	1	default
mcp	covered	1	default
http	covered	1	default