executions.list
Every execution this process remembers, newest first, narrowed by state or by capability: the ones it ran and the ones `majordomus run` in another process of the checkout reported to it, each with who started it. The counts beside them — remembered, active, queued, live channels — are what a control plane shows without asking a second question.
Every execution this process remembers, newest first, narrowed by state or by capability: the ones it ran and the ones `majordomus run` in another process of the checkout reported to it, each with who started it. The counts beside them — remembered, active, queued, live channels — are what a control plane shows without asking a second question.
- query
- behaviorally_verified
- module executions
- #executions
- #control-plane
Exposure
Where this one definition is reachable. Absence is explicit: a surface not listed does not carry it.
| surface | as |
|---|---|
| MCP | tool majordomus_executions resource majordomus://executions |
| HTTP | GET /api/v1/executions operationId executions.list |
| command line | majordomus executions list |
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 · ListInput
The input of
executions.list.| property | type | required | description |
|---|---|---|---|
| capability | string | null | no | Only executions of this capability. |
| limit | integer | null | no | How many, newest first; the default and the bound are both 200. |
| state | one of 2 | no | Only executions in this state. |
JSON Schema
{
"$defs": {
"ExecutionState": {
"description": "Where an execution is in its life.\n\nThe transitions are the whole contract, and `ExecutionState::may_move_to` is the one\nplace they are written down: the engine asks before every change, the store refuses a\nmove it did not allow, and a client that reads a final state never sees it move again.\n\n```text\n queued ──► running ──┬──► succeeded\n │ ├──► failed\n │ └──► cancelling ──┬──► cancelled\n │ ├──► succeeded\n └──► cancelled └──► failed\n```\n\nThere is no `starting`. An in-process engine claims an execution and enters its handler\nin the same instant, so a state between the two would be one no client could ever\nobserve and every client would have to handle.",
"oneOf": [
{
"const": "queued",
"description": "Accepted, and no worker has picked it up.",
"type": "string"
},
{
"const": "running",
"description": "The handler is running.",
"type": "string"
},
{
"const": "cancelling",
"description": "Cancellation was asked for and the handler has not stopped yet.",
"type": "string"
},
{
"const": "succeeded",
"description": "The handler returned an output.",
"type": "string"
},
{
"const": "failed",
"description": "The handler returned an error, or the worker could not run it.",
"type": "string"
},
{
"const": "cancelled",
"description": "It stopped because it was asked to.",
"type": "string"
}
]
}
},
"additionalProperties": false,
"description": "The input of `executions.list`.",
"properties": {
"capability": {
"description": "Only executions of this capability.",
"type": [
"string",
"null"
]
},
"limit": {
"description": "How many, newest first; the default and the bound are both `200`.",
"format": "uint",
"minimum": 0,
"type": [
"integer",
"null"
]
},
"state": {
"anyOf": [
{
"$ref": "#/$defs/ExecutionState"
},
{
"type": "null"
}
],
"description": "Only executions in this state."
}
},
"title": "ListInput",
"type": "object"
}output · ExecutionList
The answer of
executions.list.| property | type | required | description |
|---|---|---|---|
| active | integer | yes | How many are not finished. |
| count | integer | yes | How many are answered here. |
| executions | array | yes | The executions, newest first. |
| live_channels | integer | yes | How many live channels are following them. |
| queued | integer | yes | How many are waiting for a worker. |
| remembered | integer | yes | How many this process remembers in total, before the filter. |
JSON Schema
{
"$defs": {
"Actor": {
"description": "Who asked, and which peer they are when this process knows.",
"properties": {
"kind": {
"$ref": "#/$defs/ActorKind",
"description": "Where the request came from."
},
"peer": {
"description": "The peer id, for a call that arrived through an MCP session.",
"type": [
"string",
"null"
]
},
"pid": {
"description": "The process that ran it, for an execution another process ran and reported to this\none: the work happened there, and this process holds what it was told about it.",
"format": "uint32",
"minimum": 0,
"type": [
"integer",
"null"
]
}
},
"required": [
"kind"
],
"type": "object"
},
"ActorKind": {
"description": "Who asked for the execution. Not an authorisation decision — this server authenticates\nnobody — but a fact worth carrying into the audit line and the UI.",
"oneOf": [
{
"const": "http",
"description": "An HTTP client, which includes the Cockpit.",
"type": "string"
},
{
"const": "mcp",
"description": "An MCP client attached to this process.",
"type": "string"
},
{
"const": "cli",
"description": "A command line: this process's own, or `majordomus run` in another process of the\nsame checkout that reported its execution to this server, with its pid.",
"type": "string"
},
{
"const": "internal",
"description": "This executable's own tests and benchmarks.",
"type": "string"
}
]
},
"ExecutionDiagnostic": {
"description": "A structured finding an execution reported on its way, distinct from its outcome.",
"properties": {
"code": {
"description": "A stable machine-readable code.",
"type": "string"
},
"detail": {
"description": "The rest, when there is more.",
"type": [
"string",
"null"
]
},
"severity": {
"$ref": "#/$defs/Severity",
"description": "How bad."
},
"suggestion": {
"description": "What to do about it, when there is something.",
"type": [
"string",
"null"
]
},
"summary": {
"description": "One line, for a person.",
"type": "string"
}
},
"required": [
"severity",
"code",
"summary"
],
"type": "object"
},
"ExecutionError": {
"description": "Why an execution ended badly, in the repository's diagnostic vocabulary rather than in\nRust's: a code a program branches on, a sentence a person reads, and where to look.\n\nA panic message and a backtrace are never in here. The engine catches a panicking\nhandler and reports `internal` with the execution's correlation id; the panic itself is\non the process's own error stream, where the operator running the server can read it.",
"properties": {
"code": {
"description": "`invalid_input`, `not_found`, `refused`, `forbidden`, `internal`, `cancelled`, `unavailable`.",
"type": "string"
},
"correlation_id": {
"description": "The execution this failure belongs to, so a log line and a UI agree.",
"type": "string"
},
"message": {
"description": "What went wrong, for a person.",
"type": "string"
},
"suggestion": {
"description": "What to do about it, when there is something.",
"type": [
"string",
"null"
]
}
},
"required": [
"code",
"message",
"correlation_id"
],
"type": "object"
},
"ExecutionId": {
"description": "The identity of one execution: `x-<UTC timestamp>-<8 hex>`.\n\nThe shape is the layer's own — a task is `t-20260905034523-a9f1` — so that an id read\nin a log, a URL or a browser tab is recognisable as this repository's without a\ndependency on a UUID crate. The timestamp orders ids by creation for a reader; the\nsuffix, not the timestamp, is what makes two ids created in the same second differ.",
"type": "string"
},
"ExecutionLinks": {
"description": "Where to read more about one execution, in this server's own terms.\n\nEvery value is derived from the registry's declared routes and from the live channel's\nown constant, so a route that moves moves here too and no client holds a path this\nserver does not serve.",
"properties": {
"cancel": {
"description": "Where to ask it to stop: `POST /api/v1/executions/cancel`.",
"type": "string"
},
"cockpit": {
"description": "The page a person opens.",
"type": "string"
},
"events": {
"description": "The retained history: `GET /api/v1/executions/events?id=…`.",
"type": "string"
},
"self": {
"description": "The snapshot: `GET /api/v1/executions/get?id=…`.",
"type": "string"
},
"websocket": {
"description": "The live channel, from the beginning: `GET /events?execution=…`.",
"type": "string"
}
},
"required": [
"self",
"events",
"cancel",
"websocket",
"cockpit"
],
"type": "object"
},
"ExecutionState": {
"description": "Where an execution is in its life.\n\nThe transitions are the whole contract, and `ExecutionState::may_move_to` is the one\nplace they are written down: the engine asks before every change, the store refuses a\nmove it did not allow, and a client that reads a final state never sees it move again.\n\n```text\n queued ──► running ──┬──► succeeded\n │ ├──► failed\n │ └──► cancelling ──┬──► cancelled\n │ ├──► succeeded\n └──► cancelled └──► failed\n```\n\nThere is no `starting`. An in-process engine claims an execution and enters its handler\nin the same instant, so a state between the two would be one no client could ever\nobserve and every client would have to handle.",
"oneOf": [
{
"const": "queued",
"description": "Accepted, and no worker has picked it up.",
"type": "string"
},
{
"const": "running",
"description": "The handler is running.",
"type": "string"
},
{
"const": "cancelling",
"description": "Cancellation was asked for and the handler has not stopped yet.",
"type": "string"
},
{
"const": "succeeded",
"description": "The handler returned an output.",
"type": "string"
},
{
"const": "failed",
"description": "The handler returned an error, or the worker could not run it.",
"type": "string"
},
{
"const": "cancelled",
"description": "It stopped because it was asked to.",
"type": "string"
}
]
},
"ExecutionView": {
"description": "One execution with the links to everything else about it.",
"properties": {
"actor": {
"$ref": "#/$defs/Actor",
"description": "Who asked for it."
},
"cancellable": {
"description": "Whether asking to cancel this execution will do anything: the capability's policy.",
"type": "boolean"
},
"capability": {
"description": "The capability that ran, by its canonical id.",
"type": "string"
},
"correlation_id": {
"description": "The id used in this process's logs and tracing spans for this execution; the\nexecution id itself, carried under the name a reader of a log expects.",
"type": "string"
},
"created_at": {
"description": "When it was accepted, RFC 3339 in UTC.",
"type": "string"
},
"diagnostics": {
"description": "The findings it reported.",
"items": {
"$ref": "#/$defs/ExecutionDiagnostic"
},
"type": "array"
},
"duration_ms": {
"description": "How long it ran, in milliseconds, once it has finished.",
"format": "uint64",
"minimum": 0,
"type": [
"integer",
"null"
]
},
"error": {
"anyOf": [
{
"$ref": "#/$defs/ExecutionError"
},
{
"type": "null"
}
],
"description": "Why it failed, for a failed execution and never before."
},
"event_count": {
"description": "How many events it has produced, including the ones no longer retained.",
"format": "uint64",
"minimum": 0,
"type": "integer"
},
"events_truncated": {
"description": "Whether the retained event history has lost its oldest entries to the bound.",
"type": "boolean"
},
"finished_at": {
"description": "When it reached a final state.",
"type": [
"string",
"null"
]
},
"id": {
"$ref": "#/$defs/ExecutionId",
"description": "The identity."
},
"input": {
"description": "The input it was given, with every value the input schema marks sensitive replaced."
},
"last_sequence": {
"description": "The sequence number of the last event: the cursor a client subscribes from.",
"format": "uint64",
"minimum": 0,
"type": "integer"
},
"links": {
"$ref": "#/$defs/ExecutionLinks",
"description": "Where to read more."
},
"output": {
"description": "What the handler returned, for a succeeded execution and never before."
},
"progress": {
"anyOf": [
{
"$ref": "#/$defs/ProgressView"
},
{
"type": "null"
}
],
"description": "The last progress the handler reported."
},
"repository": {
"$ref": "#/$defs/RepositoryRef",
"description": "Which repository it ran against."
},
"started_at": {
"description": "When the handler was entered.",
"type": [
"string",
"null"
]
},
"state": {
"$ref": "#/$defs/ExecutionState",
"description": "Where it is."
},
"steps": {
"description": "The steps it entered, in order.",
"items": {
"$ref": "#/$defs/StepView"
},
"type": "array"
},
"title": {
"description": "That capability's title, so a list needs no second lookup.",
"type": "string"
}
},
"required": [
"id",
"capability",
"title",
"state",
"created_at",
"input",
"last_sequence",
"event_count",
"events_truncated",
"cancellable",
"actor",
"repository",
"correlation_id",
"links"
],
"type": "object"
},
"ProgressView": {
"description": "How far along an execution is.",
"properties": {
"current": {
"description": "Units done.",
"format": "uint64",
"minimum": 0,
"type": "integer"
},
"message": {
"description": "What is being done, for a reader.",
"type": [
"string",
"null"
]
},
"total": {
"description": "Units in total, when the handler knows how many.",
"format": "uint64",
"minimum": 0,
"type": [
"integer",
"null"
]
}
},
"required": [
"current"
],
"type": "object"
},
"RepositoryRef": {
"description": "Which repository, and which checkout of it, an execution ran against.\n\nAn execution is never run against \"wherever this process happens to be\": the engine\nstamps the repository the index was read from, and a request that names a different one\nis refused. The path itself is not here — this value is served to whoever can reach the\nsocket, and where the checkout sits on the host is of no use to them.",
"properties": {
"branch": {
"description": "The branch checked out, when git can say.",
"type": [
"string",
"null"
]
},
"id": {
"description": "The stable identity two processes over one checkout both compute.",
"type": "string"
},
"name": {
"description": "The repository's name: the last component of its root.",
"type": "string"
}
},
"required": [
"name",
"id"
],
"type": "object"
},
"Severity": {
"description": "How bad a diagnostic is. `Error` excludes the file it concerns from the index and puts\nthe index into the degraded state; `Warning` and `Info` do neither.",
"oneOf": [
{
"const": "info",
"description": "Worth knowing; changes nothing.",
"type": "string"
},
{
"const": "warning",
"description": "Something to look at; the object is still served.",
"type": "string"
},
{
"const": "error",
"description": "The file is excluded and the index is degraded.",
"type": "string"
}
]
},
"StepState": {
"description": "Where a step of an execution stands.",
"oneOf": [
{
"const": "running",
"description": "Entered and not finished.",
"type": "string"
},
{
"const": "completed",
"description": "Finished, and what it was asked to do happened.",
"type": "string"
},
{
"const": "failed",
"description": "Finished, and it did not.",
"type": "string"
}
]
},
"StepView": {
"description": "One named phase of an execution, as the handler reported it.",
"properties": {
"detail": {
"description": "What it said when it finished, when it said anything.",
"type": [
"string",
"null"
]
},
"finished_at": {
"description": "When it finished, when it has.",
"type": [
"string",
"null"
]
},
"name": {
"description": "A stable name, unique within the execution.",
"type": "string"
},
"started_at": {
"description": "When it was entered, RFC 3339 in UTC.",
"type": "string"
},
"state": {
"$ref": "#/$defs/StepState",
"description": "Where it stands."
},
"title": {
"description": "One line for a reader.",
"type": "string"
}
},
"required": [
"name",
"title",
"state",
"started_at"
],
"type": "object"
}
},
"description": "The answer of `executions.list`.",
"properties": {
"active": {
"description": "How many are not finished.",
"format": "uint",
"minimum": 0,
"type": "integer"
},
"count": {
"description": "How many are answered here.",
"format": "uint",
"minimum": 0,
"type": "integer"
},
"executions": {
"description": "The executions, newest first.",
"items": {
"$ref": "#/$defs/ExecutionView"
},
"type": "array"
},
"live_channels": {
"description": "How many live channels are following them.",
"format": "uint",
"minimum": 0,
"type": "integer"
},
"queued": {
"description": "How many are waiting for a worker.",
"format": "uint",
"minimum": 0,
"type": "integer"
},
"remembered": {
"description": "How many this process remembers in total, before the filter.",
"format": "uint",
"minimum": 0,
"type": "integer"
}
},
"required": [
"count",
"remembered",
"active",
"queued",
"live_channels",
"executions"
],
"title": "ExecutionList",
"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.