# Outcomes and changes

A cloud run returns what its agent wrote to the outbox (`/outbox`, named to the runner as `WORKBENCH_OUTPUT_DIR`), with an optional `outcome.json` declaration naming the files, and, for a repository run, the changes it made. A kept outcome is announced with an `outcome.available` event before the terminal event, and the run's `outcome_size` is set.

Outcomes larger than 50 MB are not kept: collection stops at the first file that would pass the limit, the run still ends, and its sandbox is still deleted. Files are redacted like events: injected secret values become `[redacted]`.

All routes here need a key with `runs:read` or a signed-in member, and answer 404 until the run has kept an outcome.

## List returned files

`GET /v1/runs/:id/outcome/files`

Response `200`:

```json
{
    "files": [
        {
            "path": "reports/findings.html",
            "name": "Findings.html",
            "media_type": "text/html",
            "size": 18342,
            "description": "The collected research report"
        }
    ]
}
```

Names, media types, and descriptions come from the run's `outcome.json` declaration when it has one. Archive metadata is not listed.

## Download one file

`GET /v1/runs/:id/outcome/files/<path>`

Each path segment is URL encoded. Honors one `Range`. HTML, SVG, and unknown types are served as attachments. Every response is `nosniff` and, except a PDF, sandboxed.

## Download the outcome archive

`GET /v1/runs/:id/outcome`

The files the run returned and the changes it made, as a tar, with the review diffs and a summary under `.workbench/`. The MCP `wait` tool returns this URL as `outcome_url`; it is not signed, so download it with the same bearer key.

## Read a run's changes

`GET /v1/runs/:id/changes`

The patch a repository run made, as `text/x-diff`: everything in the checkout measured against the base commit, including commits the agent made, with `.gitignore` applied. It is kept whatever happened on GitHub, for cancelled and failed runs too. Apply it with `git apply`:

```sh
curl -s https://api.workbenches.dev/v1/runs/wb_.../changes \
  -H "Authorization: Bearer $WORKBENCHES_KEY" | git apply
```

A patch over 10 MB is not kept; the outcome carries a `changes_too_large` warning instead. A run that changed nothing, or is not a repository run, answers 404.

## Worker runs

A worker uploads its run's outcome as a gzip tar of the `wb outcome --export` tree, at most 50 MB decompressed, once. It is then served by the same routes as a cloud run's.