HTTP API: executions

Running a capability of this registry as work that can be watched: started, followed event by event over the live channel, read back afterwards, and asked to stop. One plane per checkout: `majordomus run` executes in its own process and reports the execution to the server already serving the checkout, so that server lists it beside its own; with no server it says that nothing else can see the run. In memory; an execution does not outlive the server that holds it.

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.

executions

GET /api/v1/executions executions.list

List executions

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
benchmark required
cache disabled
MCP tool majordomus_executions
MCP resource {"name": "executions", "uri": "majordomus://executions"}
$ executions list

Query parameters

name	type	required	description	examples
state	ExecutionState \| null	no	Only executions in this state.
capability	string	no	Only executions of this capability.
limit	integer (uint)	no	How many, newest first; the default and the bound are both `200`.	recent: 50

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/executions?limit=50"

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	ExecutionList	List executions: 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.

POST /api/v1/executions/cancel executions.cancel

Ask an execution to stop

Set the execution's cancellation flag and say so on its stream. Cancellation is cooperative: a task looks at its flag and stops, and a capability whose policy says it is not cancellable runs to completion — which the answer says rather than pretending otherwise.

command
behaviorally_verified
benchmark waived: transient_state
cache disabled
MCP tool majordomus_execution_cancel
$ executions cancel

Request body — CancelInput, JSON

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 -X POST "http://127.0.0.1:8741/api/v1/executions/cancel" -H "content-type: application/json" -d '{}'

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	CancelReport	Ask an execution to stop: 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.
422	ErrorBody	`refused`: The command was understood and turned down for the reason the message gives.
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.

GET /api/v1/executions/demonstrate executions.demonstrate

Demonstrate an execution

Walk a given number of steps, reporting each one, logging a line and advancing progress, then finish — or fail at a step you name. It exists so that an operator, a probe and an end-to-end test can prove the whole path works without waiting for real work: it reads nothing, writes nothing, and its only effect is the events it produces. It looks at its cancellation flag between steps and while it waits, so cancelling it stops it.

query
behaviorally_verified
benchmark required
cache disabled
MCP tool majordomus_demonstrate_execution

Query parameters

name	type	required	description	examples
steps	integer (uint64)	no	How many steps to walk through.	immediate: 1
delay_ms	integer (uint64)	no	How long each step takes, in milliseconds. Bounded at ten seconds a step, so this cannot be used to hold a worker.	immediate: 0
fail_at	integer (uint64)	no	Fail on this step instead of completing, to show what a failure looks like.

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/executions/demonstrate?steps=1&delay_ms=0"

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	DemonstrateReport	Demonstrate an execution: 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.

GET /api/v1/executions/events executions.events

An execution's event history

The retained events of one execution, oldest first, after a sequence number. This is what a browser reads after a reload and what a client reads after a reconnect: the page carries the cursor to open the live channel with, so nothing is missed between the history and the stream.

query
behaviorally_verified
benchmark waived: transient_state
cache disabled
MCP tool majordomus_execution_events
$ executions events

Query parameters

name	type	required	description
id	string	yes	The execution's id.
after	integer (uint64)	no	Only events after this sequence number: the cursor a reconnecting client holds.
limit	integer (uint)	no	How many, oldest first; the default and the bound are both `500`.

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/executions/events"

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	EventHistory	An execution's event history: 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.

GET /api/v1/executions/get executions.get

One execution

The whole of what is known about one execution: its state, its input as it was stored, its steps, its progress, its diagnostics, and its output or its error. Taken under one lock, so a snapshot that says it succeeded carries what it produced.

query
behaviorally_verified
benchmark waived: transient_state
cache disabled
MCP tool majordomus_execution
$ executions show

Query parameters

name	type	required	description	examples
id	string	yes	The execution's id.

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/executions/get"

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	ExecutionView	One execution: 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.

GET /api/v1/executions/protocol executions.protocol

The live channel's contract

Where the WebSocket is, how a subscription and a reconnect are expressed, what the server writes, and the JSON Schema of every message — derived from the Rust types that implement it, so a client validating against this is validating against the implementation. OpenAPI cannot describe a socket; this is where that contract lives.

query
behaviorally_verified
benchmark required
cache disabled
MCP tool majordomus_execution_protocol
MCP resource {"name": "execution-protocol", "uri": "majordomus://executions/protocol"}
$ executions protocol

No parameters.

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/executions/protocol"

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	ProtocolReport	The live channel's contract: 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.

POST /api/v1/executions/report executions.report

Report an execution another process runs

What `majordomus run` posts while it runs a capability in its own process and a server already serves the checkout: the execution's description and its events after the last sequence this server took. The server holds it as an execution started by the command line, with the pid, in the same store, listing, Cockpit pages and live channel as its own; applies each event once and in order, answering where the next report starts; tells the reporter when somebody asked it to stop; and fails it with `unavailable` once the reporter has been silent for 30 s. Nothing runs here. Changes this process's memory only.

command
behaviorally_verified
benchmark waived: transient_state
cache disabled

Request body — ReportInput, JSON

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 -X POST "http://127.0.0.1:8741/api/v1/executions/report" -H "content-type: application/json" -d '{}'

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	ReportAnswer	Report an execution another process runs: 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.
422	ErrorBody	`refused`: The command was understood and turned down for the reason the message gives.
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.

POST /api/v1/executions/start executions.start

Start a capability as an execution

Run any executable capability of this registry as an execution: the input is checked against that capability's own input schema, the work is queued, and this answers at once with the execution's id and the links to follow it. Nothing waits for the handler. The capability runs through the same executor every other interface calls, so there is no second implementation of anything. On the command line (`majordomus run`) it runs in that process and is reported to the server serving the checkout, when one is, through executions.report; a run never starts a server.

command
behaviorally_verified
benchmark required
cache disabled
MCP tool majordomus_execution_start
$ run

Request body — StartInput, JSON

example demonstrate

{"capability":"executions.demonstrate","input":{"steps":1,"delay_ms":0}}

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 -X POST "http://127.0.0.1:8741/api/v1/executions/start" -H "content-type: application/json" -d '{"capability":"executions.demonstrate","input":{"steps":1,"delay_ms":0}}'

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	ExecutionView	Start a capability as an execution: 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.
422	ErrorBody	`refused`: The command was understood and turned down for the reason the message gives.
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.

Actor

object

Who asked, and which peer they are when this process knows.

property	type	required	description
kind	ActorKind → ActorKind	yes	Where the request came from.
peer	string \| null	no	The peer id, for a call that arrived through an MCP session.
pid	integer \| null	no	The process that ran it, for an execution another process ran and reported to this one: the work happened there, and this process holds what it was told about it.

Used by ExecutionView

ActorKind

"http" | "mcp" | "cli" | "internal"

Who asked for the execution. Not an authorisation decision — this server authenticates nobody — but a fact worth carrying into the audit line and the UI.

httpAn HTTP client, which includes the Cockpit.
mcpAn MCP client attached to this process.
cliA command line: this process's own, or majordomus run in another process of the same checkout that reported its execution to this server, with its pid.
internalThis executable's own tests and benchmarks.

Used by Actor

CancelInput

object

The input of executions.cancel.

property	type	required	description
id	string	yes	The execution's id.

Used by executions.cancel

CancelReport

object

The answer of executions.cancel.

property	type	required	description
outcome	string	yes	What asking achieved: `requested`, `already_requested` or `already_finished`.
cancellable	boolean	yes	Whether the capability declares that it looks at its cancellation flag. When it does not, the request is recorded and the execution runs to completion.
execution	ExecutionView → ExecutionView	yes	The execution as it stands after the request.

Used by executions.cancel

DemonstrateReport

object

The answer of executions.demonstrate.

property	type	required	description
steps	integer (uint64)	yes	How many steps ran.
elapsed_ms	integer (uint64)	yes	How long it took, in milliseconds.
observed	boolean	yes	Whether anything was watching: false when it was called directly rather than as an execution, which is the difference this capability exists to show.

Used by executions.demonstrate

EventHistory

object

The answer of executions.events: one page of an execution's retained history.

property	type	required	description
execution_id	string	yes	The execution the events belong to.
state	ExecutionState → ExecutionState	yes	Where the execution stands now, so a client needs one request rather than two.
events	array of ExecutionEvent → ExecutionEvent	yes	The events, oldest first.
last_sequence	integer (uint64)	yes	The sequence of the last event here: the cursor for the next page, and the one to open the live channel with.
more	boolean	yes	Whether more events follow this page right now.
truncated	boolean	yes	Whether events before this page had already been dropped by the store's bound.

Used by executions.events

ExecutionDiagnostic

object

A structured finding an execution reported on its way, distinct from its outcome.

property	type	required	description
severity	Severity → Severity	yes	How bad.
code	string	yes	A stable machine-readable code.
summary	string	yes	One line, for a person.
detail	string \| null	no	The rest, when there is more.
suggestion	string \| null	no	What to do about it, when there is something.

Used by ExecutionEvent ExecutionView

ExecutionError

object

Why an execution ended badly, in the repository's diagnostic vocabulary rather than in Rust's: a code a program branches on, a sentence a person reads, and where to look.

A panic message and a backtrace are never in here. The engine catches a panicking handler and reports internal with the execution's correlation id; the panic itself is on the process's own error stream, where the operator running the server can read it.

property	type	required	description
code	string	yes	`invalid_input`, `not_found`, `refused`, `forbidden`, `internal`, `cancelled`, `unavailable`.
message	string	yes	What went wrong, for a person.
suggestion	string \| null	no	What to do about it, when there is something.
correlation_id	string	yes	The execution this failure belongs to, so a log line and a UI agree.

Used by ExecutionEvent ExecutionView

ExecutionEvent

one of 12 variants

One event about one execution.

sequence is dense and starts at 1 within an execution: a client that has seen sequence n knows it has missed something when the next event it reads is not n + 1, and asks for the gap by cursor rather than reloading the world.

property	type	required	description
schema_version	string	yes	The protocol version, `PROTOCOL_VERSION`.
event_id	string	yes	The identity of this event: the execution's id and the sequence, so a client that deduplicates needs no composite key of its own.
execution_id	ExecutionId → ExecutionId	yes	The execution it is about.
sequence	integer (uint64)	yes	Its position in that execution's stream, from 1, without gaps.
timestamp	string	yes	When the event was produced, RFC 3339 in UTC.

variant The execution was accepted and exists. Carries what it will run and with what, redacted, so a client that joins at the first event needs nothing else to render a heading.

type	"execution.created"	yes
data	object	yes

variant It is waiting for a worker.

type	"execution.queued"	yes
data	object	yes

variant A worker picked it up and is about to enter the handler.

type

"execution.started"

yes

variant How far along it is.

type	"execution.progress"	yes
data	ProgressView → ProgressView	yes

variant A named phase was entered.

type	"execution.step.started"	yes
data	object	yes

variant A named phase finished.

type	"execution.step.completed"	yes
data	object	yes

variant A line of output.

type	"execution.log"	yes
data	object → LogStream	yes

variant A structured finding, distinct from the outcome.

type	"execution.diagnostic"	yes
data	ExecutionDiagnostic → ExecutionDiagnostic	yes

variant Cancellation was asked for; the handler has not stopped yet.

type	"execution.cancelling"	yes
data	object	yes

variant It stopped because it was asked to.

type

"execution.cancelled"

yes

variant It finished, and the handler returned an output.

The output is on this event and not on one of its own, because a client must never be able to read "succeeded" and find no result: the state and the value it produced are one fact and travel together.

type	"execution.completed"	yes
data	object	yes

variant It finished, and it did not.

type	"execution.failed"	yes
data	object → ExecutionError	yes

Used by EventHistory ReportInput

ExecutionId

string

The identity of one execution: x-<UTC timestamp>-<8 hex>.

The shape is the layer's own — a task is t-20260905034523-a9f1 — so that an id read in a log, a URL or a browser tab is recognisable as this repository's without a dependency on a UUID crate. The timestamp orders ids by creation for a reader; the suffix, not the timestamp, is what makes two ids created in the same second differ.

Used by ExecutionEvent ExecutionView

ExecutionLinks

object

Where to read more about one execution, in this server's own terms.

Every value is derived from the registry's declared routes and from the live channel's own constant, so a route that moves moves here too and no client holds a path this server does not serve.

property	type	required	description
self	string	yes	The snapshot: `GET /api/v1/executions/get?id=…`.
events	string	yes	The retained history: `GET /api/v1/executions/events?id=…`.
cancel	string	yes	Where to ask it to stop: `POST /api/v1/executions/cancel`.
websocket	string	yes	The live channel, from the beginning: `GET /events?execution=…`.
cockpit	string	yes	The page a person opens.

Used by ExecutionView

ExecutionList

object

The answer of executions.list.

property	type	required	description
count	integer (uint)	yes	How many are answered here.
remembered	integer (uint)	yes	How many this process remembers in total, before the filter.
active	integer (uint)	yes	How many are not finished.
queued	integer (uint)	yes	How many are waiting for a worker.
live_channels	integer (uint)	yes	How many live channels are following them.
executions	array of ExecutionView → ExecutionView	yes	The executions, newest first.

Used by executions.list

ExecutionState

Where an execution is in its life.

The transitions are the whole contract, and ExecutionState::may_move_to is the one place they are written down: the engine asks before every change, the store refuses a move it did not allow, and a client that reads a final state never sees it move again.

  queued ──► running ──┬──► succeeded
     │                 ├──► failed
     │                 └──► cancelling ──┬──► cancelled
     │                                   ├──► succeeded
     └──► cancelled                      └──► failed

There is no starting. An in-process engine claims an execution and enters its handler in the same instant, so a state between the two would be one no client could ever observe and every client would have to handle.

queuedAccepted, and no worker has picked it up.
runningThe handler is running.
cancellingCancellation was asked for and the handler has not stopped yet.
succeededThe handler returned an output.
failedThe handler returned an error, or the worker could not run it.
cancelledIt stopped because it was asked to.

Used by executions.list EventHistory ExecutionView

ExecutionView

object

One execution with the links to everything else about it.

property	type	required	description
id	ExecutionId → ExecutionId	yes	The identity.
capability	string	yes	The capability that ran, by its canonical id.
title	string	yes	That capability's title, so a list needs no second lookup.
state	ExecutionState → ExecutionState	yes	Where it is.
created_at	string	yes	When it was accepted, RFC 3339 in UTC.
started_at	string \| null	no	When the handler was entered.
finished_at	string \| null	no	When it reached a final state.
duration_ms	integer \| null	no	How long it ran, in milliseconds, once it has finished.
input	any	yes	The input it was given, with every value the input schema marks sensitive replaced.
output	any	no	What the handler returned, for a succeeded execution and never before.
error	ExecutionError \| null → ExecutionError	no	Why it failed, for a failed execution and never before.
progress	ProgressView \| null → ProgressView	no	The last progress the handler reported.
steps	array of StepView → StepView	no	The steps it entered, in order.
diagnostics	array of ExecutionDiagnostic → ExecutionDiagnostic	no	The findings it reported.
last_sequence	integer (uint64)	yes	The sequence number of the last event: the cursor a client subscribes from.
event_count	integer (uint64)	yes	How many events it has produced, including the ones no longer retained.
events_truncated	boolean	yes	Whether the retained event history has lost its oldest entries to the bound.
cancellable	boolean	yes	Whether asking to cancel this execution will do anything: the capability's policy.
actor	Actor → Actor	yes	Who asked for it.
repository	RepositoryRef → RepositoryRef	yes	Which repository it ran against.
correlation_id	string	yes	The id used in this process's logs and tracing spans for this execution; the execution id itself, carried under the name a reader of a log expects.
links	ExecutionLinks → ExecutionLinks	yes	Where to read more.

Used by executions.get executions.start CancelReport ExecutionList ReportAnswer

LimitsView

object

What this process's execution store keeps.

property	type	required	description
max_executions	integer (uint)	yes	How many executions are remembered.
max_events	integer (uint)	yes	How many events are retained per execution.
max_log_chars	integer (uint)	yes	The longest a single log line may be.
max_running	integer (uint)	yes	How many executions run at once.
max_subscriber_queue	integer (uint)	yes	How far a live channel may fall behind before it is told to resynchronise.

Used by ProtocolReport

LogStream

"stdout" | "stderr" | "handler"

Which stream a log line came from.

stdoutThe standard output of a child process the handler ran.
stderrIts standard error.
handlerThe handler itself, saying something it wants a reader to see.

Used by ExecutionEvent

ParameterView

object

One query parameter of the live channel.

property	type	required	description
name	string	yes	Its name.
description	string	yes	What it does.
required	boolean	yes	Whether it must be given.

Used by ProtocolReport

ProgressView

object

How far along an execution is.

property	type	required	description
current	integer (uint64)	yes	Units done.
total	integer \| null	no	Units in total, when the handler knows how many.
message	string \| null	no	What is being done, for a reader.

Used by ExecutionEvent ExecutionView

ProtocolReport

object

The answer of executions.protocol: the live channel's whole contract, derived from the types that implement it.

property	type	required	description
protocol_version	string	yes	The version of the event protocol this server speaks.
websocket	string	yes	Where the live channel is: a path on this same server, not a second daemon.
subscription	array of ParameterView → ParameterView	yes	How the subscription is expressed, and what a reconnect sends.
heartbeat_seconds	integer (uint64)	yes	How many seconds of quiet before the server pings.
max_connections	integer (uint)	yes	How many live channels this process serves at once.
max_replay	integer (uint)	yes	How many retained events a scoped connection replays before going live.
event_types	array of string	yes	The event types a client may receive, from the one enum that defines them.
stream_types	array of string	yes	The stream's own control messages.
event_schema	any	yes	The JSON Schema of an event, derived from the Rust type.
stream_schema	any	yes	The JSON Schema of a control message, derived from the Rust type.
limits	LimitsView → LimitsView	yes	What the store keeps, so a client knows what it may ask for.

Used by executions.protocol

ReportAnswer

object

The answer of executions.report.

property	type	required	description
applied	integer (uint)	yes	How many of the reported events were applied.
through	integer (uint64)	yes	The reporter's sequence this server holds everything up to: the next report sends the events after it, so a lost or repeated report costs nothing.
cancel_requested	boolean	yes	Whether somebody asked this server to stop the execution. The reporter runs it, so the reporter cancels it.
execution	ExecutionView → ExecutionView	yes	The execution as this server now holds it.

Used by executions.report

ReportInput

object

The input of executions.report: what a process that runs an execution says about it to the server serving the same checkout.

property	type	required	description
id	string	yes	The execution's id, as the reporting process minted it.
capability	string	yes	The capability it runs, by its canonical id.
title	string	yes	That capability's title.
input	any	no	The input it was given, as the reporting process stored it: already redacted there, and redacted again here by this registry's schema when this registry knows it.
cancellable	boolean	no	Whether the capability stops when asked. When it does, a cancel asked of this server reaches the reporter in the answer to its next report.
pid	integer (uint32)	yes	The process that runs it.
events	array of ExecutionEvent → ExecutionEvent	no	Its events after the last sequence this server answered `through`, in its own sequence, oldest first; at most 500. Empty is a heartbeat.

Used by executions.report

RepositoryRef

object

Which repository, and which checkout of it, an execution ran against.

An execution is never run against "wherever this process happens to be": the engine stamps the repository the index was read from, and a request that names a different one is refused. The path itself is not here — this value is served to whoever can reach the socket, and where the checkout sits on the host is of no use to them.

property	type	required	description
name	string	yes	The repository's name: the last component of its root.
id	string	yes	The stable identity two processes over one checkout both compute.
branch	string \| null	no	The branch checked out, when git can say.

Used by ExecutionView

StartInput

object

The input of executions.start: which capability to run, and with what.

property	type	required	description
capability	string	yes	The canonical id of the capability to run (`health.report`, `objects.verify`).
input	any	no	Its input, as its own input schema describes it; an empty object when it takes none.

Used by executions.start

StepState

"running" | "completed" | "failed"

Where a step of an execution stands.

runningEntered and not finished.
completedFinished, and what it was asked to do happened.
failedFinished, and it did not.

Used by StepView

StepView

object

One named phase of an execution, as the handler reported it.

property	type	required	description
name	string	yes	A stable name, unique within the execution.
title	string	yes	One line for a reader.
state	StepState → StepState	yes	Where it stands.
started_at	string	yes	When it was entered, RFC 3339 in UTC.
finished_at	string \| null	no	When it finished, when it has.
detail	string \| null	no	What it said when it finished, when it said anything.

Used by ExecutionView