OCX message. A JSON block in a forum post or a ticket change, fenced in Markdown: write it with a line

```json

, the JSON, and a line

```

; a reader also takes a bare

```

fence. Other text may come before or after it, and nodes ignore it; keep it short. An artifact holds one OCX message: a reader takes the first fenced block whose JSON has an ocx key, and ignores any other. Every message has "ocx": 1, a kind, and node: the one node it is for, named by its repository's server-code (40 hex digits, matched exactly). There are four kinds:

• Requests, run and stop. A node acts on one only when it is for that node and the Fossil user it came from holds admin or setup.
• Reports, started and ended. Only the node a run is for writes them, as its own Fossil user.

Every message but a run names the run it is about in its field run: the run's Fossil hash, in full, in hex. It is written where that run is, as a reply in its thread or as a change to its ticket. Several runs may share a thread or a ticket; each is answered on its own. A message never changes: an edit of one is ignored, so to change a request, stop it and send another.

Run. The OCX message of kind run: a request that a node run one program. Its fields, besides ocx, kind and node, are these, and those that Runner, Subscription and Limits add:

{"ocx": 1, "kind": "run", "node": "6cbe285e95a3a124176569ee9243f2a4e9ecdc20",
 "objective": "Build check-in abc123 for the board; it passes when the build succeeds.",
 "runner": "command", "command": ["make", "board"], "checkout": "abc123",
 "user": "builder", "session": false, "limits": {"wall": "30m"}}

• objective (text): what the job is for, and what counts as passing. Only a run has one.
• runner: how the node runs the program (see Runner).
• user (text): the Fossil user the program acts as.
• session (true or false): how long the program runs.
  • false, the default: to completion. It starts, does its work and exits, like a CI check, a build or an on-target test.
  • true: as a session. It stays running, and the node gives it, one at a time, in the order they arrived, each post or check-in the run subscribes to (see Subscription), until it exits, is stopped, or reaches its limits.
• limits: what the program may use (see Limits).

Started and ended. The node's reports on a run, written where the run is.

{"ocx": 1, "kind": "ended", "node": "6cbe…", "run": "FULL-HASH-OF-THE-RUN", "outcome": "exited", "exit": 0}

• started: the run's program is running. Its program starts once, so a run gets at most one started, a session too, however many posts it is given.
• ended: the run's program is not running, and never will be again. A run gets exactly one, and its outcome says why:
  • refused: the node did not start it, because it cannot give it what it asks (its runner, its user or its limits); no started was written;
  • exited: the program finished by itself; exit holds its exit code, a whole number;
  • stopped: a stop ended it, or came before it started;
  • budget: it reached a limit, which note names in words;
  • lost: the node went down while it ran. The node writes this when it starts again, and never starts that run again.

A stop for a run that is already over does nothing. A run with a started and no ended is running; a run with an ended is over. So a run's OCX messages come in one of these orders, and no other:

• run, ended (refused, or stopped before it started);
• run, started, ended;
• run, started, stop, ended.