> ## Documentation Index
> Fetch the complete documentation index at: https://niceeval.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# How the Runner Executes Evals

> Learn how the Runner creates Runs, chooses executed or adopted Attempts, and returns a receipt for later reading.

The Runner schedules selected Experiments and Evals as one Invocation. It executes work in the current process, shows progress, and writes business facts to the Record when the directory becomes quiescent.

## Invocation, Run, and Attempt

An Invocation has one `invocationId`. Each selected Experiment creates a Run, whose expected slots define the denominator for that run.

Each slot has at most one Member:

* `executed`: The Runner executed this slot's Attempt.
* `carried`: The planner automatically adopted an existing Attempt.
* `accepted`: An operator explicitly adopted an existing Attempt.

Every Member refers to an Attempt. An Attempt keeps its own `origin`, the Run and slot that actually executed it. A `carried` or `accepted` Member does not copy its Verdict, Usage, events, or other business values.

## Plan before execution

Use `niceeval exp --dry` before a run. It reads the channels needed for planning from a quiescent Record and lists why each slot will execute or be adopted.

```sh theme={null}
npx niceeval exp checkout --dry
```

Carry happens only when the terminal Verdict, input identity, timeout, and `--rerun` conditions all allow it. Identity is an opaque value with a domain; values compare only when the domains match. The target Run's `niceeval.actions` channel records the reason, eligibility, and input information.

The Runner starts the Attempts that need execution only after planning. See [Rerun and Carry Results](/docs/tutorials/rerun-and-cache) for details.

## Feedback from the current process

Progress, active Attempts, and short diagnostics exist only for the current process. The terminal can render them, and `--json` writes the same machine-readable feedback.

```sh theme={null}
npx niceeval exp checkout --json
```

`exp --json` emits NDJSON. Progress and diagnostic records describe the current Invocation; they are not a Record decoding format. Exactly one final record is a lightweight `InvocationReceipt`:

```json theme={null}
{
  "type": "receipt",
  "receipt": {
    "invocationId": "01J8ZK3M6P4T7V9X2C5N8QW0RY",
    "runIds": ["01J9ZK3M6P4T7V9X2C5N8QW0RY"],
    "startedAt": "2026-08-09T10:00:00.000Z",
    "completedAt": "2026-08-09T10:01:00.000Z",
    "completion": "completed"
  }
}
```

The receipt identifies this Invocation, its Runs, timing, and completion only. To inspect Verdicts, Usage, diagnostics, or report aggregates, reread the quiescent Record using its `runIds`.

## Reporter

A Reporter connects only to the current Invocation. It can send information already known to the process to an external system, and `--junit` writes a file for a CI platform to consume.

Neither output owns the Record. The quiescent Record's named channels retain the recorded Verdict, Usage, assertions, and diagnostics. A later step projects an AnalysisSample from the receipt's `runIds`, then uses `show`, `view`, or `view --out` to inspect complete results.

## Inspect after the run

After the Runner ends, inspect a historical result with an explicit Run selection:

```sh theme={null}
npx niceeval show --run 01J9ZK3M6P4T7V9X2C5N8QW0RY
npx niceeval view --run 01J9ZK3M6P4T7V9X2C5N8QW0RY --no-open
```

Without a locator or `--run`, `show` and `view` read every slot whose identity still matches the current project. A locator or `--run` reads named historical facts. The internal host forms a pure `AnalysisSample`, projects the facts declared by the Report, and produces a fixed `ReportExecution`. Published Runs are immutable; another view creates a new selection and execution.

## Completion status

The process exit status reflects the Verdicts, execution errors, and Invocation completion known to the Runner. CI can use that status as its gate. A machine caller can read the final receipt, then use `runIds` to select what to show or export.

Input errors that prevent an Invocation from being created have no receipt. Correct the command, Experiment, or selection condition before trying again.