brief.session

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

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