@opensoftware/contracts 2.3.0 → 2.4.0

package/openapi/openapi.json

@@ -2,7 +2,7 @@
   "openapi": "3.1.0",
   "info": {
     "title": "Open Software Factory contracts",
-    "version": "2.3.0",
+    "version": "2.4.0",
     "description": "The shared formats as named models, and the HTTP APIs of the modules. Generated by `pnpm build` in contracts/ from typespec/. Do not edit.",
     "license": {
       "name": "Apache-2.0",
@@ -10,6 +10,54 @@
     }
   },
   "paths": {
+    "/v1/doctor/pings/{id}": {
+      "get": {
+        "operationId": "ForemanApi_getDoctorPing",
+        "description": "The `doctor.ping@v1` event with this ID, when the foreman's consumer received it since the server started (ADR\n0120). `console doctor --deep` asks for it after it published the event.",
+        "parameters": [
+          {
+            "name": "id",
+            "in": "path",
+            "required": true,
+            "schema": {
+              "type": "string"
+            }
+          }
+        ],
+        "responses": {
+          "200": {
+            "description": "The request has succeeded.",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/DoctorPingSeen"
+                }
+              }
+            }
+          },
+          "401": {
+            "description": "Access is unauthorized.",
+            "content": {
+              "application/problem+json": {
+                "schema": {
+                  "$ref": "#/components/schemas/ApiProblem"
+                }
+              }
+            }
+          },
+          "404": {
+            "description": "The server cannot find the requested resource.",
+            "content": {
+              "application/problem+json": {
+                "schema": {
+                  "$ref": "#/components/schemas/ApiProblem"
+                }
+              }
+            }
+          }
+        }
+      }
+    },
     "/v1/gates": {
       "post": {
         "operationId": "GatekeeperApi_requestGate",
@@ -117,6 +165,94 @@
         }
       }
     },
+    "/v1/gates/{gateId}/decisions": {
+      "post": {
+        "operationId": "GatekeeperApi_decideGate",
+        "description": "A person decides a pending gate (ADR 0118): 403 when they are in no group the gate waits for, 409 when the gate\nis no longer pending.",
+        "parameters": [
+          {
+            "name": "gateId",
+            "in": "path",
+            "required": true,
+            "schema": {
+              "type": "string"
+            }
+          }
+        ],
+        "responses": {
+          "200": {
+            "description": "The request has succeeded.",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/GateView"
+                }
+              }
+            }
+          },
+          "400": {
+            "description": "The server could not understand the request due to invalid syntax.",
+            "content": {
+              "application/problem+json": {
+                "schema": {
+                  "$ref": "#/components/schemas/ApiProblem"
+                }
+              }
+            }
+          },
+          "401": {
+            "description": "Access is unauthorized.",
+            "content": {
+              "application/problem+json": {
+                "schema": {
+                  "$ref": "#/components/schemas/ApiProblem"
+                }
+              }
+            }
+          },
+          "403": {
+            "description": "Access is forbidden.",
+            "content": {
+              "application/problem+json": {
+                "schema": {
+                  "$ref": "#/components/schemas/ApiProblem"
+                }
+              }
+            }
+          },
+          "404": {
+            "description": "The server cannot find the requested resource.",
+            "content": {
+              "application/problem+json": {
+                "schema": {
+                  "$ref": "#/components/schemas/ApiProblem"
+                }
+              }
+            }
+          },
+          "409": {
+            "description": "The request conflicts with the current state of the server.",
+            "content": {
+              "application/problem+json": {
+                "schema": {
+                  "$ref": "#/components/schemas/ApiProblem"
+                }
+              }
+            }
+          }
+        },
+        "requestBody": {
+          "required": true,
+          "content": {
+            "application/json": {
+              "schema": {
+                "$ref": "#/components/schemas/GateDecisionRequest"
+              }
+            }
+          }
+        }
+      }
+    },
     "/v1/health": {
       "get": {
         "operationId": "HealthApi_getHealth",
@@ -152,7 +288,7 @@
     "/v1/inbox": {
       "get": {
         "operationId": "IntakeApi_listWorkItems",
-        "description": "The 50 latest work items, the one received last first; with `status`, only the work items in that status.",
+        "description": "A page of the latest work items, the one received last first; with `status`, only the work items in that status.\n`limit` work items at most, 50 by default; `cursor` is the `next` of the page before (ADR 0115).",
         "parameters": [
           {
             "name": "status",
@@ -162,6 +298,28 @@
               "$ref": "#/components/schemas/WorkItemStatus"
             },
             "explode": false
+          },
+          {
+            "name": "limit",
+            "in": "query",
+            "required": false,
+            "schema": {
+              "type": "integer",
+              "format": "int32",
+              "minimum": 1,
+              "maximum": 500
+            },
+            "explode": false
+          },
+          {
+            "name": "cursor",
+            "in": "query",
+            "required": false,
+            "schema": {
+              "type": "string",
+              "minLength": 1
+            },
+            "explode": false
           }
         ],
         "responses": {
@@ -201,7 +359,7 @@
     "/v1/runs": {
       "post": {
         "operationId": "ForemanApi_startRun",
-        "description": "Start a run of the factory's workflow for a work item. The same work item again answers the run it started.",
+        "description": "Start a run of the factory's workflow for a work item. The same work item again answers its newest run.",
         "parameters": [],
         "responses": {
           "200": {
@@ -258,7 +416,7 @@
       },
       "get": {
         "operationId": "ForemanApi_listRuns",
-        "description": "The runs of the server, running runs first, then the runs that ended, the one that ended last first; with `state`, only the runs in that state (ADR 0071).",
+        "description": "A page of the runs of the server, running runs first, then the runs that ended, the one that ended last first; with\n`state`, only the runs in that state (ADR 0071). `limit` runs at most, 50 by default; `cursor` is the `next` of the\npage before (ADR 0115). With `state`, a page may hold fewer runs than `limit` and still have a `next`.",
         "parameters": [
           {
             "name": "state",
@@ -268,6 +426,28 @@
               "$ref": "#/components/schemas/RunState"
             },
             "explode": false
+          },
+          {
+            "name": "limit",
+            "in": "query",
+            "required": false,
+            "schema": {
+              "type": "integer",
+              "format": "int32",
+              "minimum": 1,
+              "maximum": 500
+            },
+            "explode": false
+          },
+          {
+            "name": "cursor",
+            "in": "query",
+            "required": false,
+            "schema": {
+              "type": "string",
+              "minLength": 1
+            },
+            "explode": false
           }
         ],
         "responses": {
@@ -352,6 +532,84 @@
         }
       }
     },
+    "/v1/runs/{runId}/retry": {
+      "post": {
+        "operationId": "ForemanApi_retryRun",
+        "description": "Run a run that failed or was cancelled again, as a new run that names it (ADR 0105).",
+        "parameters": [
+          {
+            "name": "runId",
+            "in": "path",
+            "required": true,
+            "schema": {
+              "type": "string"
+            }
+          }
+        ],
+        "responses": {
+          "201": {
+            "description": "The request has succeeded and a new resource has been created as a result.",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/RunView"
+                }
+              }
+            }
+          },
+          "400": {
+            "description": "The server could not understand the request due to invalid syntax.",
+            "content": {
+              "application/problem+json": {
+                "schema": {
+                  "$ref": "#/components/schemas/ApiProblem"
+                }
+              }
+            }
+          },
+          "401": {
+            "description": "Access is unauthorized.",
+            "content": {
+              "application/problem+json": {
+                "schema": {
+                  "$ref": "#/components/schemas/ApiProblem"
+                }
+              }
+            }
+          },
+          "404": {
+            "description": "The server cannot find the requested resource.",
+            "content": {
+              "application/problem+json": {
+                "schema": {
+                  "$ref": "#/components/schemas/ApiProblem"
+                }
+              }
+            }
+          },
+          "409": {
+            "description": "The request conflicts with the current state of the server.",
+            "content": {
+              "application/problem+json": {
+                "schema": {
+                  "$ref": "#/components/schemas/ApiProblem"
+                }
+              }
+            }
+          }
+        },
+        "requestBody": {
+          "required": true,
+          "content": {
+            "application/json": {
+              "schema": {
+                "$ref": "#/components/schemas/RunRetry"
+              }
+            }
+          }
+        }
+      }
+    },
     "/v1/runs/{runId}/signals": {
       "post": {
         "operationId": "ForemanApi_signalRun",
@@ -632,6 +890,58 @@
         ],
         "description": "Who caused something: a person, or an automated trigger such as a cron rule or an alert."
       },
+      "AdapterVersion": {
+        "type": "object",
+        "properties": {
+          "port": {
+            "anyOf": [
+              {
+                "type": "string",
+                "const": "harness"
+              },
+              {
+                "type": "string",
+                "const": "sandbox"
+              },
+              {
+                "type": "string",
+                "const": "forge"
+              },
+              {
+                "type": "string",
+                "const": "inference"
+              }
+            ],
+            "description": "The port under `providers`: harness, sandbox, forge or inference."
+          },
+          "name": {
+            "type": "string",
+            "minLength": 1
+          },
+          "version": {
+            "type": "string",
+            "minLength": 1,
+            "description": "The exact version that factory.lock pins for the range under `providers.<port>.<name>`, else that range (ADR 0125)."
+          },
+          "command": {
+            "type": "array",
+            "items": {
+              "type": "string"
+            },
+            "description": "The command line the foreman builds when no map names the adapter: npx at the version."
+          },
+          "configured": {
+            "type": "string",
+            "minLength": 1,
+            "description": "The variable whose map gives the adapter's command line instead, for example \"FOREMAN_HARNESSES\"."
+          }
+        },
+        "required": [
+          "port",
+          "name"
+        ],
+        "description": "foreman: a run of the factory's workflow for one work item, as the HTTP API shows it (ADR 0067).An adapter of the factory's `providers` and the version a run of it asks for (ADR 0110)."
+      },
       "Agent": {
         "type": "object",
         "properties": {
@@ -824,6 +1134,13 @@
         ],
         "additionalProperties": false
       },
+      "BlockedOn": {
+        "type": "string",
+        "enum": [
+          "checks"
+        ],
+        "description": "What a blocked stage waits for: the checks of the run's pull request. A gate has its own `gate.requested@v1`."
+      },
       "BundlePath": {
         "type": "string",
         "pattern": "^(?!/)(?!.*(^|/)\\.\\.(/|$))[^\\\\]+$",
@@ -865,6 +1182,84 @@
         "pattern": "^[0-9a-f]{7,40}$",
         "description": "A Git commit hash, abbreviated (7+) or full. The factory version is the commit of the factory definition."
       },
+      "DoctorPing": {
+        "type": "object",
+        "properties": {
+          "specversion": {
+            "type": "string",
+            "const": "1.0"
+          },
+          "id": {
+            "$ref": "#/components/schemas/Identifier",
+            "description": "Unique per source. A consumer that sees the same source and id twice handles the event once."
+          },
+          "source": {
+            "type": "string",
+            "minLength": 1,
+            "description": "The producing module, for example \"/osf/intake\"."
+          },
+          "type": {
+            "type": "string",
+            "const": "doctor.ping@v1"
+          },
+          "time": {
+            "type": "string",
+            "format": "date-time"
+          },
+          "subject": {
+            "type": "string",
+            "description": "The ID of the thing the event is about: work item, gate, run, score or pull request."
+          },
+          "datacontenttype": {
+            "type": "string",
+            "const": "application/json"
+          },
+          "dataschema": {
+            "type": "string",
+            "format": "uri"
+          },
+          "traceparent": {
+            "type": "string",
+            "description": "W3C trace context (CloudEvents distributed tracing extension)."
+          },
+          "data": {
+            "$ref": "#/components/schemas/DoctorPingData"
+          }
+        },
+        "required": [
+          "specversion",
+          "id",
+          "source",
+          "type",
+          "time",
+          "data"
+        ],
+        "description": "console: `console doctor --deep` checks that an event reaches the foreman (ADR 0120). The ID is fresh and random;\nthe foreman shows it on `GET /v1/doctor/pings/{id}` and acts on nothing else."
+      },
+      "DoctorPingData": {
+        "type": "object",
+        "properties": {},
+        "description": "A ping carries nothing but its ID."
+      },
+      "DoctorPingSeen": {
+        "type": "object",
+        "properties": {
+          "id": {
+            "$ref": "#/components/schemas/Identifier",
+            "description": "The event's ID."
+          },
+          "receivedAt": {
+            "type": "string",
+            "format": "date-time",
+            "description": "When the foreman received it."
+          }
+        },
+        "required": [
+          "id",
+          "receivedAt"
+        ],
+        "description": "foreman: a `doctor.ping@v1` event that its consumer received (ADR 0120)."
+      },
       "Effort": {
         "type": "string",
         "enum": [
@@ -1000,7 +1395,7 @@
             "items": {
               "$ref": "#/components/schemas/Stage"
             },
-            "description": "Stages in order. Each stage runs one agent; the agent defaults to the stage name."
+            "description": "Stages in order. Each stage runs one agent, which defaults to the stage name, or only waits (ADR 0107)."
           },
           "automations": {
             "type": "array",
@@ -1031,8 +1426,121 @@
           "factory",
           "agents"
         ],
-        "description": "`factory.yaml`: the desired state of one factory (P3). Paths are relative to the file.\nRealizes SCN-FACTORY-CODE-001: agents and prompts; MCP servers, skills and secrets per agent;\nrepositories; model and runtime; automations; scorers and benchmarks.",
-        "additionalProperties": false
+        "description": "`factory.yaml`: the desired state of one factory (P3). Paths are relative to the file.\nRealizes SCN-FACTORY-CODE-001: agents and prompts; MCP servers, skills and secrets per agent;\nrepositories; model and runtime; automations; scorers and benchmarks.",
+        "additionalProperties": false
+      },
+      "FactoryLock": {
+        "type": "object",
+        "properties": {
+          "version": {
+            "type": "number",
+            "const": 1,
+            "description": "The version of the lock's format."
+          },
+          "mcp": {
+            "type": "object",
+            "properties": {},
+            "unevaluatedProperties": {
+              "$ref": "#/components/schemas/FactoryLockMcpPin"
+            },
+            "description": "The registry MCP servers, by their reference in factory.yaml, for example `registry:io.github.acme/tracker@1.4`."
+          },
+          "adapters": {
+            "type": "object",
+            "properties": {},
+            "unevaluatedProperties": {
+              "type": "object",
+              "properties": {},
+              "unevaluatedProperties": {
+                "$ref": "#/components/schemas/FactoryLockAdapterPin"
+              }
+            },
+            "description": "The adapters under `providers` that `factory plan --adapters` pinned, per port and adapter name (ADR 0125). A pin\ncounts only while its `range` is the range factory.yaml declares."
+          }
+        },
+        "required": [
+          "version",
+          "mcp"
+        ],
+        "description": "factory.lock next to factory.yaml (ADR 0020, ADR 0125): the exact versions that `factory plan` pinned. factory-spec\nwrites it; the foreman reads the pins of its adapters."
+      },
+      "FactoryLockAdapterPin": {
+        "type": "object",
+        "properties": {
+          "range": {
+            "type": "string",
+            "minLength": 1,
+            "description": "The range under `providers` that the pin was resolved from, for example \"^2\"."
+          },
+          "version": {
+            "type": "string",
+            "minLength": 1,
+            "description": "The exact version, for example \"2.3.1\"."
+          }
+        },
+        "required": [
+          "range",
+          "version"
+        ],
+        "description": "One adapter's npm package `@opensoftware/<port>-<name>` at the newest version inside its range.",
+        "additionalProperties": false
+      },
+      "FactoryLockMcpPin": {
+        "type": "object",
+        "properties": {
+          "name": {
+            "type": "string",
+            "minLength": 1
+          },
+          "version": {
+            "type": "string",
+            "minLength": 1
+          },
+          "package": {
+            "type": "object",
+            "properties": {
+              "registryType": {
+                "type": "string",
+                "const": "npm"
+              },
+              "identifier": {
+                "type": "string",
+                "minLength": 1
+              },
+              "version": {
+                "type": "string",
+                "minLength": 1
+              }
+            },
+            "required": [
+              "registryType",
+              "identifier",
+              "version"
+            ]
+          },
+          "remote": {
+            "type": "object",
+            "properties": {
+              "type": {
+                "type": "string",
+                "minLength": 1
+              },
+              "url": {
+                "type": "string",
+                "minLength": 1
+              }
+            },
+            "required": [
+              "type",
+              "url"
+            ]
+          }
+        },
+        "required": [
+          "name",
+          "version"
+        ],
+        "description": "One registry MCP server at its exact version, with the npm package or the remote it starts."
       },
       "FormatVersion": {
         "type": "integer",
@@ -1155,6 +1663,37 @@
           "expired"
         ]
       },
+      "GateDecisionRequest": {
+        "type": "object",
+        "properties": {
+          "decision": {
+            "anyOf": [
+              {
+                "type": "string",
+                "const": "approved"
+              },
+              {
+                "type": "string",
+                "const": "rejected"
+              }
+            ]
+          },
+          "by": {
+            "$ref": "#/components/schemas/Actor",
+            "description": "The person who decides; their `id` must be a member of a group in `waitingFor`."
+          },
+          "reason": {
+            "type": "string",
+            "minLength": 1,
+            "description": "The reason of a rejection."
+          }
+        },
+        "required": [
+          "decision",
+          "by"
+        ],
+        "description": "gatekeeper: a person's decision of a pending gate through the API, as a member of a group the gate waits for\n(ADR 0118). It decides like a reply \"approve\" or \"reject <reason>\" in the gate's channel."
+      },
       "GateRecord": {
         "type": "object",
         "properties": {
@@ -2077,6 +2616,132 @@
           "commented"
         ]
       },
+      "RunAction": {
+        "type": "object",
+        "properties": {
+          "type": {
+            "$ref": "#/components/schemas/RunSignalType"
+          },
+          "by": {
+            "$ref": "#/components/schemas/Actor",
+            "description": "The person who sent it."
+          },
+          "at": {
+            "type": "string",
+            "format": "date-time",
+            "description": "When the foreman took it."
+          },
+          "message": {
+            "type": "string",
+            "minLength": 1,
+            "description": "The steering message of \"steer\"."
+          }
+        },
+        "required": [
+          "type",
+          "by",
+          "at"
+        ],
+        "description": "foreman: a signal a person sent a run, as the run records it (ADR 0118)."
+      },
+      "RunBlocked": {
+        "type": "object",
+        "properties": {
+          "specversion": {
+            "type": "string",
+            "const": "1.0"
+          },
+          "id": {
+            "$ref": "#/components/schemas/Identifier",
+            "description": "Unique per source. A consumer that sees the same source and id twice handles the event once."
+          },
+          "source": {
+            "type": "string",
+            "minLength": 1,
+            "description": "The producing module, for example \"/osf/intake\"."
+          },
+          "type": {
+            "type": "string",
+            "const": "run.blocked@v1"
+          },
+          "time": {
+            "type": "string",
+            "format": "date-time"
+          },
+          "subject": {
+            "type": "string",
+            "description": "The ID of the thing the event is about: work item, gate, run, score or pull request."
+          },
+          "datacontenttype": {
+            "type": "string",
+            "const": "application/json"
+          },
+          "dataschema": {
+            "type": "string",
+            "format": "uri"
+          },
+          "traceparent": {
+            "type": "string",
+            "description": "W3C trace context (CloudEvents distributed tracing extension)."
+          },
+          "data": {
+            "$ref": "#/components/schemas/RunBlockedData"
+          }
+        },
+        "required": [
+          "specversion",
+          "id",
+          "source",
+          "type",
+          "time",
+          "data"
+        ],
+        "description": "foreman: a stage of a run waits for the checks of its pull request (ADR 0127). The ID is `<run ID>.blocked.<stage>`."
+      },
+      "RunBlockedData": {
+        "type": "object",
+        "properties": {
+          "runId": {
+            "$ref": "#/components/schemas/Identifier"
+          },
+          "workItemId": {
+            "$ref": "#/components/schemas/Identifier"
+          },
+          "stage": {
+            "$ref": "#/components/schemas/Name",
+            "description": "The stage that waits."
+          },
+          "waitsFor": {
+            "$ref": "#/components/schemas/BlockedOn"
+          },
+          "pullRequest": {
+            "type": "string",
+            "format": "uri",
+            "description": "The pull request whose checks the stage waits for."
+          },
+          "checks": {
+            "type": "array",
+            "items": {
+              "type": "string"
+            },
+            "description": "The names of the checks the stage waits for."
+          },
+          "requester": {
+            "$ref": "#/components/schemas/Actor"
+          },
+          "source": {
+            "$ref": "#/components/schemas/Name"
+          }
+        },
+        "required": [
+          "runId",
+          "workItemId",
+          "stage",
+          "waitsFor",
+          "requester",
+          "source"
+        ]
+      },
       "RunCompleted": {
         "type": "object",
         "properties": {
@@ -2180,6 +2845,14 @@
           "evidenceBundle": {
             "type": "string",
             "format": "uri"
+          },
+          "retryOf": {
+            "$ref": "#/components/schemas/Identifier",
+            "description": "The run before, when this run runs a work item again (ADR 0105)."
+          },
+          "reason": {
+            "type": "string",
+            "description": "Why the stage the run ended at failed, when the foreman knows it (ADR 0127)."
           }
         },
         "required": [
@@ -2201,6 +2874,11 @@
             "items": {
               "$ref": "#/components/schemas/RunView"
             }
+          },
+          "next": {
+            "type": "string",
+            "minLength": 1,
+            "description": "The cursor of the next page, while more runs follow (ADR 0115)."
           }
         },
         "required": [
@@ -2286,6 +2964,22 @@
         ],
         "description": "Set at launch through OTEL_RESOURCE_ATTRIBUTES, so it is on every span of the run."
       },
+      "RunRetry": {
+        "type": "object",
+        "properties": {
+          "by": {
+            "$ref": "#/components/schemas/Actor",
+            "description": "The person who asks."
+          },
+          "from": {
+            "$ref": "#/components/schemas/Name"
+          }
+        },
+        "required": [
+          "by"
+        ],
+        "description": "foreman: run a run that failed or was cancelled again, as a new run (ADR 0105). The new run starts at the first stage\nthat did not succeed, or at `from`, a stage at or before it."
+      },
       "RunSignal": {
         "type": "object",
         "properties": {
@@ -2296,6 +2990,10 @@
             "type": "string",
             "minLength": 1,
             "description": "The steering message. Required with \"steer\"."
+          },
+          "by": {
+            "$ref": "#/components/schemas/Actor",
+            "description": "The person who sends the signal; the run then records it in `actions` (ADR 0118)."
           }
         },
         "required": [
@@ -2489,6 +3187,10 @@
           },
           "source": {
             "$ref": "#/components/schemas/Name"
+          },
+          "retryOf": {
+            "$ref": "#/components/schemas/Identifier",
+            "description": "The run before, when this run runs a work item again (ADR 0105)."
           }
         },
         "required": [
@@ -2519,7 +3221,21 @@
           "runId": {
             "type": "string",
             "pattern": "^run_[0-9a-f]{20}$",
-            "description": "\"run_\" and 20 hex digits of the SHA-256 of the work item's ID."
+            "description": "\"run_\" and 20 hex digits of the SHA-256 of the work item's ID; for the n-th run of the work item, n ≥ 2, of \"<work item ID>#<n>\" (ADR 0105)."
+          },
+          "attempt": {
+            "type": "integer",
+            "minimum": 1,
+            "description": "Which run of the work item this is: 1 when absent (ADR 0105)."
+          },
+          "retryOf": {
+            "type": "string",
+            "pattern": "^run_[0-9a-f]{20}$",
+            "description": "The run before this one, which a person ran again (ADR 0105)."
+          },
+          "retriedBy": {
+            "$ref": "#/components/schemas/Actor",
+            "description": "The person who ran the run before again (ADR 0105)."
           },
           "workItem": {
             "$ref": "#/components/schemas/WorkItem"
@@ -2532,13 +3248,20 @@
             "$ref": "#/components/schemas/CommitHash",
             "description": "The commit of the factory definition the run started with."
           },
+          "adapters": {
+            "type": "array",
+            "items": {
+              "$ref": "#/components/schemas/AdapterVersion"
+            },
+            "description": "The adapters of the factory's `providers` and the versions the run asks for (ADR 0110)."
+          },
           "state": {
             "$ref": "#/components/schemas/RunState"
           },
           "pullRequest": {
             "type": "string",
             "format": "uri",
-            "description": "The last pull request link that an agent of the run wrote (ADR 0069)."
+            "description": "The run's pull request: the forge's of the run's branch, the one an agent stated, or else the last link an agent wrote (ADR 0069, ADR 0109)."
           },
           "folder": {
             "type": "string",
@@ -2563,6 +3286,13 @@
               "$ref": "#/components/schemas/StageView"
             },
             "description": "The stages of the workflow, in order."
+          },
+          "actions": {
+            "type": "array",
+            "items": {
+              "$ref": "#/components/schemas/RunAction"
+            },
+            "description": "The signals that named their person, oldest first (ADR 0118)."
           }
         },
         "required": [
@@ -2573,8 +3303,7 @@
           "state",
           "startedAt",
           "stages"
-        ],
-        "description": "foreman: a run of the factory's workflow for one work item, as the HTTP API shows it (ADR 0067)."
+        ]
       },
       "Sandbox": {
         "type": "object",
@@ -2945,6 +3674,10 @@
           "evidence": {
             "$ref": "#/components/schemas/EvidenceRequirement",
             "description": "Whether the stage must produce an evidence bundle."
+          },
+          "wait": {
+            "type": "boolean",
+            "description": "The stage runs no agent: it only waits for its checks, its evidence and its gate, then succeeds (ADR 0107). It\nnames no agent and at least one of checks, evidence \"required\" or gate."
           }
         },
         "required": [
@@ -2973,7 +3706,11 @@
           },
           "agent": {
             "$ref": "#/components/schemas/Name",
-            "description": "The agent that runs the stage."
+            "description": "The agent that runs the stage; the stage's name for a stage that only waits (ADR 0107)."
+          },
+          "wait": {
+            "type": "boolean",
+            "description": "True for a stage that only waits: it runs no agent and starts no session (ADR 0107)."
           },
           "state": {
             "$ref": "#/components/schemas/StageState"
@@ -2982,6 +3719,11 @@
             "type": "string",
             "description": "The harness session of the stage's agent, once it started."
           },
+          "spanId": {
+            "type": "string",
+            "pattern": "^[0-9a-f]{16}$",
+            "description": "The span of the stage in the run's trace, once it started: the first 16 hex digits of the SHA-256 of\n`<runId>:<stage index>` (ADR 0087, ADR 0121)."
+          },
           "gateId": {
             "type": "string",
             "pattern": "^g[0-9a-f]{16}$",
@@ -2994,6 +3736,11 @@
             },
             "description": "The checks the stage waits for, once the foreman read them (ADR 0069)."
           },
+          "waitingSince": {
+            "type": "string",
+            "format": "date-time",
+            "description": "Since when the stage waits for its checks, its gate or a person, while it is blocked (ADR 0106)."
+          },
           "takenOverAt": {
             "type": "string",
             "format": "date-time",
@@ -3004,6 +3751,11 @@
             "minLength": 1,
             "description": "Why the stage ended without success, when the foreman knows."
           },
+          "note": {
+            "type": "string",
+            "minLength": 1,
+            "description": "Why the stage gave the run no pull request: a refused link, a branch the forge has none of, or the forge adapter's error (ADR 0109)."
+          },
           "startedAt": {
             "type": "string",
             "format": "date-time"
@@ -3101,6 +3853,11 @@
             "items": {
               "$ref": "#/components/schemas/WorkItemView"
             }
+          },
+          "next": {
+            "type": "string",
+            "minLength": 1,
+            "description": "The cursor of the next page, while more work items follow (ADR 0115)."
           }
         },
         "required": [
@@ -3238,6 +3995,81 @@
         ],
         "description": "intake: one submission that asked for a work item."
       },
+      "WorkRetryRequested": {
+        "type": "object",
+        "properties": {
+          "specversion": {
+            "type": "string",
+            "const": "1.0"
+          },
+          "id": {
+            "$ref": "#/components/schemas/Identifier",
+            "description": "Unique per source. A consumer that sees the same source and id twice handles the event once."
+          },
+          "source": {
+            "type": "string",
+            "minLength": 1,
+            "description": "The producing module, for example \"/osf/intake\"."
+          },
+          "type": {
+            "type": "string",
+            "const": "work.retry-requested@v1"
+          },
+          "time": {
+            "type": "string",
+            "format": "date-time"
+          },
+          "subject": {
+            "type": "string",
+            "description": "The ID of the thing the event is about: work item, gate, run, score or pull request."
+          },
+          "datacontenttype": {
+            "type": "string",
+            "const": "application/json"
+          },
+          "dataschema": {
+            "type": "string",
+            "format": "uri"
+          },
+          "traceparent": {
+            "type": "string",
+            "description": "W3C trace context (CloudEvents distributed tracing extension)."
+          },
+          "data": {
+            "$ref": "#/components/schemas/WorkRetryRequestedData"
+          }
+        },
+        "required": [
+          "specversion",
+          "id",
+          "source",
+          "type",
+          "time",
+          "data"
+        ],
+        "description": "intake: a person asked to run a work item's run again (ADR 0105). The ID is `<run ID>.retry`."
+      },
+      "WorkRetryRequestedData": {
+        "type": "object",
+        "properties": {
+          "workItemId": {
+            "$ref": "#/components/schemas/Identifier"
+          },
+          "runId": {
+            "$ref": "#/components/schemas/Identifier",
+            "description": "The run to run again: the run the work item follows."
+          },
+          "requester": {
+            "$ref": "#/components/schemas/Actor",
+            "description": "The person who asked."
+          }
+        },
+        "required": [
+          "workItemId",
+          "runId",
+          "requester"
+        ]
+      },
       "WorkSubmission": {
         "type": "object",
         "properties": {