# Working with runs

Follow a run, read what failed, and open the environment the failure happened in.

## Following a run

```bash
haystack verify watch      # block until it finishes
haystack verify status     # per-test verdicts, counts, live environments
haystack verify list       # runs newest first
```

`watch` is the one to use in CI. It exits **0** when everything passed, **1** when tests failed, and **2** when the run itself broke. A broken run is not a failing test, and treating them the same turns infrastructure trouble into a red build nobody trusts.

## Reading what failed

```bash
haystack verify findings         # every problem found, with the readings that moved
haystack verify show latest 3    # one test in full: finding, readings, timeline, SDK log
haystack verify diff latest 3    # base-vs-head screenshots
```

Every run argument takes a run id, a chapter id (which resolves to the newest run of that chapter), or `latest`.

## Opening the environment

A failing test keeps its environment alive, so you can look at the failure rather than reconstruct it from logs.

```bash
haystack verify open latest 3 --live   # the failing test's live environment
haystack verify shell latest 3         # a terminal inside that environment
haystack verify artifacts latest       # pull screenshots, DOM snapshots and video locally
haystack verify reopen latest 3        # fresh compute against the retained state
```

Environments expire. `status` shows the expiry alongside each live URL, and `reopen` attaches new compute to state retained after the original sandbox went away.

## Every subcommand

| Command | Purpose |
|---|---|
| `status` | One screen for a run: per-test verdicts, counts, live environments and expiry |
| `watch` | Follow a run until it finishes; exit 0 passed, 1 tests failed, 2 run broke |
| `list` | Runs newest first: chapter, verdict counts, age |
| `findings` | Every problem the run found, with the readings that moved and live links |
| `show` | One test in full: finding, changed readings, request timeline, SDK log lines |
| `diff` | Base-vs-head screenshot differ for one test |
| `open` | Open a run artifact, or a failing test's live environment |
| `shell` | Terminal into a failing test's live universe |
| `artifacts` | Pull a run's screenshots, DOM snapshots and videos locally |
| `reopen` | Attach fresh compute to a failing test's retained state |
| `sandboxes` | Sandbox inventory with run attribution; --kill-stale reclaims superseded ones |