@shipeasy/openapi 2.4.0 → 2.5.0

package/openapi.json

@@ -113,6 +113,11 @@
       "parent": "Ops",
       "description": "Comments on a queue item — the discussion thread that hangs off any bug,\nfeature request, or auto-filed error/alert ticket. Append a comment or read\nthe thread; one level of threaded replies via `parentId`.\n\n**Mentions.** `@teammate` in a body raises an in-app notification for that\nperson; `@shipeasy` asks Jarvis (the AI agent) to read the item and reply.\nComments authored by Jarvis carry `authorType: system`."
     },
+    {
+      "name": "Investigations",
+      "parent": "Ops",
+      "description": "Investigation records on a queue item — the structured, read-only write-ups\nan AI agent produces while working it (findings / a blocking question / QA\nnotes), plus the `working` run rows an ack or an AI hand-off opens. This is\nthe AI-write seam the cockpit's detail panel renders: `list` reads what a\nprevious run found, `create` appends a new record, and `update` fills in the\n`working` run record you were handed (findings, PR, confidence) as you work."
+    },
     {
       "name": "Projects",
       "description": "Projects: the account-level container every other resource is scoped to.\n\n**Account-level, not bound-project-level.** Both operations resolve from the caller's credential rather than the `.shipeasy`-bound project — `current` reads the project the auth header maps to, and `upsert` find-or-creates under the session's owner. Neither touches the local `.shipeasy` binding; recording the result there is a consumer side-effect layered on top.\n\n**Idempotent upsert.** A project is keyed by `(owner_email, domain)`. Calling `upsert` again with the same domain returns the existing project with `created: false`, so it is safe to run on every install."
@@ -2544,7 +2549,7 @@
       "post": {
         "operationId": "createConfig",
         "summary": "Create a dynamic config",
-        "description": "Creates a new config with the given `schema`. The initial `value` (or an empty object) is published as version 1 on **every** env.\n\nReturns `409` if `name` already exists in the project, `400` if `value` doesn't validate against `schema`.\n\n**Use cases**\n\n- **Minimal create** — `name` + `schema`. Initial value defaults to `{}`.\n- **Seeded create** — supply a flat `value` to publish the same object on every env.\n- **Per-env seed** — supply a `{ env: value }` map for different per-env starting values.",
+        "description": "Creates a new config with the given `schema`. The initial `value` (or an empty object) is published as version 1 on **every** env.\n\nReturns `409` if `name` already exists in the project, `400` if `value` doesn't validate against `schema`.\n\n**Use cases**\n\n- **Minimal create** — `name` + `schema`. Initial value defaults to `{}`.\n- **Seeded create** — supply a flat `value` to publish the same object on every env.\n- **Per-env seed** — supply a `{ env: value }` map under `value`, or pass the env keys `dev`/`staging`/`prod` directly (each overrides `value` for that env and is published at version 1).",
         "tags": [
           "Configs"
         ],
@@ -2609,8 +2614,8 @@
                   }
                 },
                 "perEnvSeed": {
-                  "summary": "Per-env seed",
-                  "description": "Pass a `{ env: value }` map to seed different initial values per env.",
+                  "summary": "Per-env seed (env keys)",
+                  "description": "Pass the env keys directly to seed different initial values per env. Each overrides `value` for that env and is published at version 1.",
                   "value": {
                     "name": "pricing.tiers",
                     "schema": {
@@ -2624,40 +2629,28 @@
                         "tiers"
                       ]
                     },
-                    "value": {
-                      "dev": {
-                        "tiers": [
-                          {
-                            "name": "free"
-                          },
-                          {
-                            "name": "pro"
-                          },
-                          {
-                            "name": "enterprise"
-                          }
-                        ]
-                      },
-                      "stage": {
-                        "tiers": [
-                          {
-                            "name": "free"
-                          },
-                          {
-                            "name": "pro"
-                          }
-                        ]
-                      },
-                      "prod": {
-                        "tiers": [
-                          {
-                            "name": "free"
-                          },
-                          {
-                            "name": "pro"
-                          }
-                        ]
-                      }
+                    "dev": {
+                      "tiers": [
+                        {
+                          "name": "free"
+                        },
+                        {
+                          "name": "pro"
+                        },
+                        {
+                          "name": "enterprise"
+                        }
+                      ]
+                    },
+                    "prod": {
+                      "tiers": [
+                        {
+                          "name": "free"
+                        },
+                        {
+                          "name": "pro"
+                        }
+                      ]
                     }
                   }
                 }
@@ -2901,7 +2894,7 @@
       "patch": {
         "operationId": "updateConfig",
         "summary": "Update a dynamic config",
-        "description": "Partial update. When `value` is supplied it is **republished on every env** (new version per env). When `schema` is supplied it replaces the current schema; every existing value is re-validated.\n\nFor env-scoped edits, use the draft/publish flow (`PUT /{id}/drafts` then `POST /{id}/publish`) instead.\n\n**Use cases**\n\n- **Republish flat value** — `{ \"value\": {…} }` sets the same value on every env.\n- **Schema migration** — `{ \"schema\": {…} }` replaces the schema; existing values are re-validated.\n- **Env-scoped edits** — use `PUT /{id}/drafts` + `POST /{id}/publish` instead of PATCH.",
+        "description": "Partial update. When `value` is supplied it is **republished on every env** (new version per env). A per-env key (`dev`/`staging`/`prod`) publishes a new version to **only that env**, immediately, overriding `value` for it. When `schema` is supplied it replaces the current schema; every existing value is re-validated.\n\n**Use cases**\n\n- **Republish flat value** — `{ \"value\": {…} }` sets the same value on every env.\n- **Publish one env** — `{ \"prod\": {…} }` publishes a new version to prod only, instantly.\n- **Schema migration** — `{ \"schema\": {…} }` replaces the schema; existing values are re-validated.",
         "tags": [
           "Configs"
         ],
@@ -2943,6 +2936,25 @@
                     }
                   }
                 },
+                "prodOnly": {
+                  "summary": "Per-env — publish prod only",
+                  "description": "Publishes a new version to prod only, immediately. dev/staging untouched.",
+                  "value": {
+                    "prod": {
+                      "tiers": [
+                        {
+                          "name": "free"
+                        },
+                        {
+                          "name": "pro"
+                        },
+                        {
+                          "name": "enterprise"
+                        }
+                      ]
+                    }
+                  }
+                },
                 "schemaOnly": {
                   "summary": "Schema-only update",
                   "description": "Replaces the schema. Existing values must still validate or the update fails.",
@@ -3181,6 +3193,7 @@
         ],
         "x-cli": {
           "name": "draft",
+          "hidden": true,
           "positional": [
             "id"
           ]
@@ -3267,6 +3280,7 @@
         ],
         "x-cli": {
           "name": "discard-draft",
+          "hidden": true,
           "positional": [
             "id"
           ]
@@ -3366,6 +3380,7 @@
         ],
         "x-cli": {
           "name": "publish",
+          "hidden": true,
           "positional": [
             "id"
           ]
@@ -3457,6 +3472,7 @@
         ],
         "x-cli": {
           "name": "activity",
+          "hidden": true,
           "positional": [
             "id"
           ]
@@ -3663,6 +3679,7 @@
         ],
         "x-cli": {
           "name": "versions",
+          "hidden": true,
           "positional": [
             "id"
           ]
@@ -7545,7 +7562,7 @@
         "summary": "List an item's investigation records",
         "description": "The structured, read-only investigation records on a queue item — the\nfindings / blocking questions / QA notes an AI agent posted while working\nit, plus its `working` run rows. Returns `published` records only, newest\nfirst (max 50).\n\n**Use case:** Read what a previous agent run already found before starting\nyour own investigation of the item.",
         "tags": [
-          "Ops"
+          "Investigations"
         ],
         "parameters": [
           {
@@ -7593,14 +7610,20 @@
           "UNAUTHORIZED",
           "FORBIDDEN",
           "NOT_FOUND"
-        ]
+        ],
+        "x-cli": {
+          "name": "list",
+          "positional": [
+            "handle"
+          ]
+        }
       },
       "post": {
         "operationId": "createOpsInvestigation",
         "summary": "Record an investigation",
         "description": "Append one structured investigation record to a queue item — the AI-write\nseam the cockpit's detail panel renders read-only. Post your findings\n(`kind: investigated`), a blocking question for the team (`kind:\nquestion`), or how to verify the fix (`kind: ready_for_qa` with\n`qaNotes`). Append-only and create-only, so it is safe for restricted ops\nkeys.\n\n**Use case:** After working an item, leave a findings write-up (summary,\nmarkdown findings, sources inspected, confidence) so the team — and the\nnext agent run — sees what you learned.",
         "tags": [
-          "Ops"
+          "Investigations"
         ],
         "parameters": [
           {
@@ -7688,7 +7711,110 @@
           "FORBIDDEN",
           "NOT_FOUND",
           "VALIDATION"
-        ]
+        ],
+        "x-cli": {
+          "name": "create",
+          "positional": [
+            "handle"
+          ]
+        }
+      }
+    },
+    "/api/admin/ops/{handle}/investigation/{investigationId}": {
+      "patch": {
+        "operationId": "updateOpsInvestigation",
+        "summary": "Update an investigation record",
+        "description": "Update one existing investigation record in place — the write-back seam for\nthe `working` run record you were handed when a run was launched. Fill in\nthe `summary`/`findings`, attach the fixing PR, record your `confidence`\nand the `sources` you inspected, or flip its `kind` off `working` once the\ninvestigation is done. A partial patch: send only the fields you want to\nchange. Safe for restricted ops keys (it never reads or deletes).\n\n**Use case:** A run started with an empty `working` record; as you work,\nPATCH it with your findings so the cockpit's detail panel fills in live —\nno need to append a second record.",
+        "tags": [
+          "Investigations"
+        ],
+        "parameters": [
+          {
+            "$ref": "#/components/parameters/ProjectId"
+          },
+          {
+            "name": "handle",
+            "in": "path",
+            "required": true,
+            "description": "Per-project item number (e.g. `7`) or the full ops item id.",
+            "schema": {
+              "$ref": "#/components/schemas/ResourceId"
+            }
+          },
+          {
+            "name": "investigationId",
+            "in": "path",
+            "required": true,
+            "description": "The investigation record id (from `POST`/`GET .../investigation` or the `runId` an ack/launch returned).",
+            "schema": {
+              "$ref": "#/components/schemas/ResourceId"
+            }
+          }
+        ],
+        "requestBody": {
+          "required": true,
+          "content": {
+            "application/json": {
+              "schema": {
+                "$ref": "#/components/schemas/UpdateOpsInvestigationRequest"
+              },
+              "examples": {
+                "findings": {
+                  "summary": "Fill in the run record's findings",
+                  "value": {
+                    "kind": "investigated",
+                    "summary": "Root cause is a stale KV read on the checkout flag.",
+                    "findings": "The `checkout.cta` gate is rebuilt without a CDN purge, so…",
+                    "confidence": "high",
+                    "prNumber": 4821,
+                    "prUrl": "https://github.com/acme/web/pull/4821"
+                  }
+                }
+              }
+            }
+          }
+        },
+        "responses": {
+          "200": {
+            "description": "The updated investigation record",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/OpsInvestigation"
+                }
+              }
+            }
+          },
+          "400": {
+            "$ref": "#/components/responses/BadRequest"
+          },
+          "401": {
+            "$ref": "#/components/responses/Unauthorized"
+          },
+          "403": {
+            "$ref": "#/components/responses/Forbidden"
+          },
+          "404": {
+            "$ref": "#/components/responses/NotFound"
+          },
+          "422": {
+            "$ref": "#/components/responses/UnprocessableEntity"
+          }
+        },
+        "x-error-codes": [
+          "BAD_REQUEST",
+          "UNAUTHORIZED",
+          "FORBIDDEN",
+          "NOT_FOUND",
+          "VALIDATION"
+        ],
+        "x-cli": {
+          "name": "update",
+          "positional": [
+            "handle",
+            "investigationId"
+          ]
+        }
       }
     },
     "/api/admin/agent-profiles": {
@@ -12391,6 +12517,10 @@
                         "locked": {
                           "description": "If `true`, dashboard hides edit controls (e.g. the trailing public-floor entry).",
                           "type": "boolean"
+                        },
+                        "whitelist": {
+                          "description": "Cosmetic marker. When `true`, the dashboard renders this condition as the pinned, always-first \"whitelist\" allowlist block (a direct `email`/`user_id` `in […]` list) rather than a numbered targeting step. Purely presentational — ignored by evaluation, which treats the entry as an ordinary condition.",
+                          "type": "boolean"
                         }
                       },
                       "required": [
@@ -12926,6 +13056,10 @@
                         "locked": {
                           "description": "If `true`, dashboard hides edit controls (e.g. the trailing public-floor entry).",
                           "type": "boolean"
+                        },
+                        "whitelist": {
+                          "description": "Cosmetic marker. When `true`, the dashboard renders this condition as the pinned, always-first \"whitelist\" allowlist block (a direct `email`/`user_id` `in […]` list) rather than a numbered targeting step. Purely presentational — ignored by evaluation, which treats the entry as an ordinary condition.",
+                          "type": "boolean"
                         }
                       },
                       "required": [
@@ -13322,6 +13456,10 @@
                         "locked": {
                           "description": "If `true`, dashboard hides edit controls (e.g. the trailing public-floor entry).",
                           "type": "boolean"
+                        },
+                        "whitelist": {
+                          "description": "Cosmetic marker. When `true`, the dashboard renders this condition as the pinned, always-first \"whitelist\" allowlist block (a direct `email`/`user_id` `in […]` list) rather than a numbered targeting step. Purely presentational — ignored by evaluation, which treats the entry as an ordinary condition.",
+                          "type": "boolean"
                         }
                       },
                       "required": [
@@ -15588,7 +15726,24 @@
             "description": "JSON Schema (draft 2020-12) describing the shape of the config value. Top-level `type` must be `'object'`; every published value is validated against this schema."
           },
           "value": {
+            "type": "object",
+            "additionalProperties": {},
             "description": "Initial config value. Either a single JSON object applied to every env, or a `{ env: value }` map seeding per-env values. Must match `schema`. Defaults to `{}` on every env when omitted."
+          },
+          "dev": {
+            "type": "object",
+            "additionalProperties": {},
+            "description": "Seed the **dev** env's initial value (version 1), overriding `value` for dev. Published immediately. Must match `schema`."
+          },
+          "staging": {
+            "type": "object",
+            "additionalProperties": {},
+            "description": "Seed the **staging** env's initial value (version 1), overriding `value` for staging. Published immediately. Must match `schema`."
+          },
+          "prod": {
+            "type": "object",
+            "additionalProperties": {},
+            "description": "Seed the **prod** env's initial value (version 1), overriding `value` for prod. Published immediately. Must match `schema`."
           }
         },
         "required": [
@@ -15596,7 +15751,7 @@
           "schema"
         ],
         "additionalProperties": false,
-        "description": "Body for `POST /api/admin/configs`. `name` + `schema` required."
+        "description": "Body for `POST /api/admin/configs`. `name` + `schema` required. Per-env `dev`/`staging`/`prod` values are published to that env at version 1 (overriding `value`)."
       },
       "CreateConfigResponse": {
         "type": "object",
@@ -15784,14 +15939,31 @@
             "additionalProperties": {}
           },
           "value": {
-            "description": "Flat value applied to **every** env. Publishes a new version per env. To target one env, use `PUT /{id}/drafts` then `POST /{id}/publish`."
+            "type": "object",
+            "additionalProperties": {},
+            "description": "Flat value applied to **every** env. Publishes a new version per env. To publish one env only, pass that env's key (`dev`/`staging`/`prod`) instead."
+          },
+          "dev": {
+            "type": "object",
+            "additionalProperties": {},
+            "description": "Publish a new version to the **dev** env only, immediately (no draft). Overrides `value` for dev. Must match the effective schema."
+          },
+          "staging": {
+            "type": "object",
+            "additionalProperties": {},
+            "description": "Publish a new version to the **staging** env only, immediately (no draft). Overrides `value` for staging. Must match the effective schema."
+          },
+          "prod": {
+            "type": "object",
+            "additionalProperties": {},
+            "description": "Publish a new version to the **prod** env only, immediately (no draft). Overrides `value` for prod. Must match the effective schema."
           },
           "folder": {
             "$ref": "#/components/schemas/Folder"
           }
         },
         "additionalProperties": false,
-        "description": "Body for `PATCH /api/admin/configs/{id}`. Partial — only supplied fields change. `value` republishes on every env."
+        "description": "Body for `PATCH /api/admin/configs/{id}`. Partial — only supplied fields change. `value` republishes on every env; per-env `dev`/`staging`/`prod` publish a new version to just that env."
       },
       "UpdateConfigResponse": {
         "type": "object",
@@ -15822,6 +15994,8 @@
             "$ref": "#/components/schemas/Env"
           },
           "value": {
+            "type": "object",
+            "additionalProperties": {},
             "description": "Draft value to stage on `env`. Validated against the config's current schema."
           }
         },
@@ -18135,6 +18309,17 @@
         ],
         "description": "Desired direction of movement. `higher_better` (default), `lower_better`, or `neutral` (guardrail)."
       },
+      "MetricDisplayUnit": {
+        "description": "Display unit (e.g. `ms`, `%`, `$`), or `null` when unitless.",
+        "anyOf": [
+          {
+            "type": "string"
+          },
+          {
+            "type": "null"
+          }
+        ]
+      },
       "CreateMetricWithQuery": {
         "type": "object",
         "properties": {
@@ -18158,6 +18343,9 @@
           },
           "direction": {
             "$ref": "#/components/schemas/MetricDirection"
+          },
+          "unit": {
+            "$ref": "#/components/schemas/MetricDisplayUnit"
           }
         },
         "required": [
@@ -18191,6 +18379,9 @@
           },
           "direction": {
             "$ref": "#/components/schemas/MetricDirection"
+          },
+          "unit": {
+            "$ref": "#/components/schemas/MetricDisplayUnit"
           }
         },
         "required": [
@@ -18417,6 +18608,9 @@
           },
           "direction": {
             "$ref": "#/components/schemas/MetricDirection"
+          },
+          "unit": {
+            "$ref": "#/components/schemas/MetricDisplayUnit"
           }
         },
         "required": [
@@ -18445,6 +18639,9 @@
           },
           "direction": {
             "$ref": "#/components/schemas/MetricDirection"
+          },
+          "unit": {
+            "$ref": "#/components/schemas/MetricDisplayUnit"
           }
         },
         "required": [
@@ -18470,10 +18667,13 @@
           },
           "direction": {
             "$ref": "#/components/schemas/MetricDirection"
+          },
+          "unit": {
+            "$ref": "#/components/schemas/MetricDisplayUnit"
           }
         },
         "additionalProperties": false,
-        "description": "Update-metric variant that leaves the query untouched (metadata-only edit — folder, event, winsorisation, default minimum effect of interest, direction)."
+        "description": "Update-metric variant that leaves the query untouched (metadata-only edit — folder, event, winsorisation, default minimum effect of interest, direction, display unit)."
       },
       "UpdateMetricRequest": {
         "oneOf": [
@@ -19955,6 +20155,27 @@
         "additionalProperties": false,
         "description": "The fully-resolved owner of a queue item — a person and/or an AI agent. The two halves are independent: an item may have a person, an agent, both, or neither (both `null`)."
       },
+      "OpsRunAction": {
+        "type": "string",
+        "enum": [
+          "link_pr",
+          "notify",
+          "status",
+          "superseded"
+        ],
+        "description": "The final action that closed a run record — `link_pr`/`notify` are the agent's terminal ops actions, `status` a completion status flip (ready_for_qa/resolved), `superseded` a newer ack replacing an open run."
+      },
+      "OpsRunActionOrNull": {
+        "anyOf": [
+          {
+            "$ref": "#/components/schemas/OpsRunAction"
+          },
+          {
+            "type": "null"
+          }
+        ],
+        "description": "Which final action closed the run, or `null` while it is open (or a non-run record)."
+      },
       "OpsRun": {
         "type": "object",
         "properties": {
@@ -20006,11 +20227,7 @@
             ],
             "description": "The agent-run session id recorded on the ack (dashboard deep-links to the run page), or `null`."
           },
-          "startedAt": {
-            "type": "string",
-            "description": "ISO-8601 timestamp the run started (the ack time)."
-          },
-          "completedAt": {
+          "sessionUrl": {
             "anyOf": [
               {
                 "type": "string"
@@ -20019,24 +20236,25 @@
                 "type": "null"
               }
             ],
-            "description": "ISO-8601 timestamp the run closed, or `null` while still open."
+            "description": "The run's session-page deep link, or `null`. DERIVED (never stored): rebuilt from `sessionId` + the run's trigger connector — Claude's routine id (`?trigger=`), Copilot's repo (`/tasks/`), Cursor/Jules from the id alone."
           },
-          "completedAction": {
+          "startedAt": {
+            "type": "string",
+            "description": "ISO-8601 timestamp the run started (the ack time)."
+          },
+          "completedAt": {
             "anyOf": [
               {
-                "type": "string",
-                "enum": [
-                  "link_pr",
-                  "notify",
-                  "status",
-                  "superseded"
-                ]
+                "type": "string"
               },
               {
                 "type": "null"
               }
             ],
-            "description": "Which final action closed the run — `link_pr`/`notify` are the agent's terminal ops actions, `status` a completion status flip (ready_for_qa/resolved), `superseded` a newer ack replacing it. `null` while the run is open."
+            "description": "ISO-8601 timestamp the run closed, or `null` while still open."
+          },
+          "completedAction": {
+            "$ref": "#/components/schemas/OpsRunActionOrNull"
           },
           "prNumber": {
             "anyOf": [
@@ -20067,6 +20285,7 @@
           "connectorId",
           "ackedBy",
           "sessionId",
+          "sessionUrl",
           "startedAt",
           "completedAt",
           "completedAction",
@@ -20351,6 +20570,42 @@
             ],
             "description": "Initial triage priority, or `null`."
           },
+          "status": {
+            "anyOf": [
+              {
+                "$ref": "#/components/schemas/OpsItemStatus"
+              }
+            ],
+            "description": "Initial lifecycle status; defaults to `open` when omitted."
+          },
+          "assigneeId": {
+            "anyOf": [
+              {
+                "type": "string"
+              },
+              {
+                "type": "null"
+              }
+            ],
+            "description": "The `users.id` of the person to assign as owner at creation, or `null`."
+          },
+          "subscribers": {
+            "type": "array",
+            "items": {
+              "type": "string",
+              "format": "email"
+            },
+            "default": [],
+            "description": "Emails of teammates to subscribe to this item's Slack pings at creation."
+          },
+          "tags": {
+            "type": "array",
+            "items": {
+              "type": "string"
+            },
+            "default": [],
+            "description": "Tag names to attach at creation (get-or-created by name, deduped case-insensitively)."
+          },
           "reporterEmail": {
             "anyOf": [
               {
@@ -20470,6 +20725,42 @@
             ],
             "description": "Initial triage priority, or `null`."
           },
+          "status": {
+            "anyOf": [
+              {
+                "$ref": "#/components/schemas/OpsItemStatus"
+              }
+            ],
+            "description": "Initial lifecycle status; defaults to `open` when omitted."
+          },
+          "assigneeId": {
+            "anyOf": [
+              {
+                "type": "string"
+              },
+              {
+                "type": "null"
+              }
+            ],
+            "description": "The `users.id` of the person to assign as owner at creation, or `null`."
+          },
+          "subscribers": {
+            "type": "array",
+            "items": {
+              "type": "string",
+              "format": "email"
+            },
+            "default": [],
+            "description": "Emails of teammates to subscribe to this item's Slack pings at creation."
+          },
+          "tags": {
+            "type": "array",
+            "items": {
+              "type": "string"
+            },
+            "default": [],
+            "description": "Tag names to attach at creation (get-or-created by name, deduped case-insensitively)."
+          },
           "reporterEmail": {
             "anyOf": [
               {
@@ -21431,7 +21722,7 @@
             ],
             "description": "The agent-run session id, or `null`."
           },
-          "ackedBy": {
+          "sessionUrl": {
             "anyOf": [
               {
                 "type": "string"
@@ -21440,24 +21731,21 @@
                 "type": "null"
               }
             ],
-            "description": "Email of the human who acked (run records for a human ack), or `null`."
+            "description": "The run's session-page deep link, or `null`. DERIVED (never stored): rebuilt from `sessionId` + the run's trigger connector — Claude's routine id (`?trigger=`), Copilot's repo (`/tasks/`), Cursor/Jules from the id alone. Only `working` run records carry one."
           },
-          "completedAction": {
+          "ackedBy": {
             "anyOf": [
               {
-                "type": "string",
-                "enum": [
-                  "link_pr",
-                  "notify",
-                  "status",
-                  "superseded"
-                ]
+                "type": "string"
               },
               {
                 "type": "null"
               }
             ],
-            "description": "Which final action closed a `working` run record, or `null` (open run / non-run record)."
+            "description": "Email of the human who acked (run records for a human ack), or `null`."
+          },
+          "completedAction": {
+            "$ref": "#/components/schemas/OpsRunActionOrNull"
           },
           "createdAt": {
             "type": "string",
@@ -21489,6 +21777,7 @@
           "startedAt",
           "completedAt",
           "sessionId",
+          "sessionUrl",
           "ackedBy",
           "completedAction",
           "createdAt",
@@ -21639,6 +21928,119 @@
         "additionalProperties": false,
         "description": "Body for `POST /api/admin/ops/{handle}/investigation`. `kind` is required; include at least one content field (`summary`/`findings`/`question`/`qaNotes`) — the panel renders whatever it gets."
       },
+      "UpdateOpsInvestigationRequest": {
+        "type": "object",
+        "properties": {
+          "kind": {
+            "type": "string",
+            "enum": [
+              "investigated",
+              "detected",
+              "question",
+              "ready_for_qa",
+              "working",
+              "note"
+            ],
+            "description": "Reclassify the record's lifecycle stage (e.g. flip a `working` run into `investigated` once findings land)."
+          },
+          "summary": {
+            "type": "string",
+            "maxLength": 2000,
+            "description": "One-line summary of the record."
+          },
+          "findings": {
+            "type": "string",
+            "maxLength": 50000,
+            "description": "The full findings write-up (markdown)."
+          },
+          "question": {
+            "type": "string",
+            "maxLength": 10000,
+            "description": "A blocking question for the team (markdown)."
+          },
+          "qaNotes": {
+            "type": "string",
+            "maxLength": 50000,
+            "description": "How to verify the fix — QA notes (markdown)."
+          },
+          "model": {
+            "type": "string",
+            "maxLength": 200,
+            "description": "The model the agent ran on."
+          },
+          "prNumber": {
+            "type": "integer",
+            "description": "A PR the record references."
+          },
+          "prUrl": {
+            "type": "string",
+            "format": "uri",
+            "maxLength": 2000,
+            "description": "HTML URL of that PR."
+          },
+          "sources": {
+            "type": "array",
+            "maxItems": 200,
+            "items": {
+              "type": "object",
+              "properties": {
+                "path": {
+                  "type": "string",
+                  "description": "Repo-relative file path inspected."
+                },
+                "url": {
+                  "type": "string",
+                  "description": "External link consulted."
+                },
+                "label": {
+                  "type": "string",
+                  "description": "Human-readable label for the source."
+                }
+              },
+              "additionalProperties": false,
+              "description": "One file/link inspected while producing the record."
+            },
+            "description": "The files/links inspected."
+          },
+          "confidence": {
+            "type": "string",
+            "enum": [
+              "low",
+              "medium",
+              "high"
+            ],
+            "description": "Self-reported confidence in the record."
+          },
+          "tokensUsed": {
+            "type": "integer",
+            "description": "Tokens the run consumed."
+          },
+          "durationMs": {
+            "type": "integer",
+            "description": "Run duration in milliseconds."
+          },
+          "visibility": {
+            "type": "string",
+            "enum": [
+              "draft",
+              "published"
+            ],
+            "description": "Record visibility. `draft` keeps it out of the panel; `published` surfaces it."
+          },
+          "completedAt": {
+            "type": "string",
+            "description": "ISO-8601 timestamp the work finished. Set it (or flip `kind` off `working`) to mark a run record done."
+          },
+          "sessionId": {
+            "type": "string",
+            "maxLength": 300,
+            "description": "The agent-run session id, so the dashboard can deep-link to the run."
+          }
+        },
+        "additionalProperties": false,
+        "minProperties": 1,
+        "description": "Body for `PATCH /api/admin/ops/{handle}/investigation/{investigationId}` — a partial update of one existing investigation record (typically the `working` run record you were handed). Send only the fields you want to change; at least one is required."
+      },
       "OpsAgentProfile": {
         "type": "object",
         "properties": {