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

# Traces & replay

> Every run can leave a replayable record: one NDJSON file that proves what ran, in what order, at what cost.

You ran a workflow an hour ago. It worked (or it didn't), and now someone
asks: *what exactly happened?* With most AI tooling the answer scrolled
away. With Nika the run itself is a file: every event the engine emitted,
one JSON line each, in order, with timestamps. Save it, share it, replay
it. The run is evidence, not a memory.

## Record a run

`nika run` renders a live storyboard for humans and writes an execution
journal by default to `.nika/traces/<timestamp>-<id>.ndjson`. The
verdict line prints that path — the same file
`nika compile hello hello.nika` then `nika run hello.nika` writes.

Add `--json` and the same run also streams machine events on stdout, one
NDJSON line per event — the CI and agent surface (stdout stays pure
NDJSON; nothing else is printed there):

```bash theme={"system"}
nika run hello.nika --json
```

`--resume`, `nika trace show|replay|verify` and the editor read the
journal directly. With no path, `show`, `replay`, and `verify` read the
workspace's latest journal and name it on stderr
(`nika trace: reading <path> (the workspace latest)`). Pass a path to
select another; `nika trace ls` lists the store. Opt out per run with
`--no-trace-file`, or globally with `NIKA_NO_TRACE_FILE` (`nika try`
never journals — the mock rehearsal is not a workspace run).

A refusal before execution or a queued cancellation can leave no journal.
Interruption can leave incomplete evidence. A job or receipt identity alone
does not prove that a trace exists or is sealed; `nika trace verify` reads
existing evidence and never seals it.

The journal keeps task outputs **verbatim** so a run can be replayed and
verified. Hash-chained is not confidential: `.nika/traces/` inherits the
sensitivity of whatever the workflow read, and on a shared or CI machine
that directory is a second data-at-rest surface. Treat it like the files
the run opened. A redaction posture that still verifies is a larger
conversation; this page only names the consequence.

## The event stream

A trace is the run's lifecycle spine. Each line is one event with a
unique id, a nanosecond timestamp, a `kind`, and typed fields:

* `workflow_started`, then one `task_scheduled` per task
* `task_started` when a task's dependencies clear
* `task_completed` (with `duration_ms`), or `task_failed`, or
  `task_skipped` (a `when:` gate said no), or `task_cache_hit`
  (a [resumed run](https://docs.nika.sh/guides/resume.md) reused this task's recorded work)
* `workflow_completed`, or `workflow_failed`, or `workflow_paused`
  (a human gate is waiting — the trace carries the prompt payload)

A real journal from `nika 0.123.0`: the one-task `mock/echo` hello of the
[SDK quickstart](https://docs.nika.sh/sdk/start/quickstart.md), with each event's `fields` abridged.
Every line carries `chain`, the hash that links it to the line before:

```json theme={"system"}
{"id":{"uuid":"01a16da4-ef1f-74ad-9612-4c0e6339082c"},"timestamp":1792840888095000000,"kind":"workflow_started","execution":{"uuid":"01a16da4-ef10-75cb-97fa-e0bcc8945d3c"},"chain":"7466341540fd02fca9ec21937862176b7821a52495b86d81bb5f30d16c8462dc","fields":[{"key":"workflow","value":"hello"}]}
{"id":{"uuid":"01a16da4-ef23-76bc-a7bc-432d9fb884ed"},"timestamp":1792840888099000000,"kind":"task_scheduled","execution":{"uuid":"01a16da4-ef10-75cb-97fa-e0bcc8945d3c"},"chain":"7fdea5da88635cf245dc1d3308448cb15b8a5e05f9cb0c66c5c1f9cd8f3c4978","fields":[{"key":"task","value":"greeting"}]}
{"id":{"uuid":"01a16da4-ef28-7707-a8c1-1fb798ef20c6"},"timestamp":1792840888104000000,"kind":"task_started","execution":{"uuid":"01a16da4-ef10-75cb-97fa-e0bcc8945d3c"},"chain":"907d719542dd475a93bf1d2dbe0db8b0a9a36e09a1b059c01bd23c5dfd259595","fields":[{"key":"task","value":"greeting"}]}
{"id":{"uuid":"01a16da4-ef29-708e-bd5c-ef46b9bf92bc"},"timestamp":1792840888105000000,"kind":"task_completed","execution":{"uuid":"01a16da4-ef10-75cb-97fa-e0bcc8945d3c"},"chain":"df29062d313b712b51bb43acceb3ef3f8d1b6d5454c6c3d390e0e72bf294374e","fields":[{"key":"task","value":"greeting"},{"key":"duration_ms","value":2}]}
{"id":{"uuid":"01a16da4-ef29-708e-bd5c-ef47f97e094b"},"timestamp":1792840888105000000,"kind":"workflow_completed","execution":{"uuid":"01a16da4-ef10-75cb-97fa-e0bcc8945d3c"},"chain":"bf2bbdd2f5fbd5e2c1271bbd2703f3018e49e2537b06ddcc4756360b1e382d50","fields":[{"key":"workflow","value":"hello"}]}
```

This run was not signed. On a machine with a run-signing key, a sixth line,
`run_sealed`, closes the journal.

The spine is not the whole vocabulary. Deeper kinds record retries
(`task_retrying`), cancellation (`task_cancelled`,
`workflow_cancelled`), money (`cost_incurred`), security checks
(`permit_checked`), streaming (`infer_chunk`) and the agent loop
(`agent_tools_selected`, `agent_budget_checkpoint`, and friends). The
35 event kinds of engine 0.124.1 are listed in
[Concepts · Events](https://docs.nika.sh/concepts/events.md).

Real spend also rides the spine: a priced `task_completed` carries a
`cost_usd` field next to its `tokens` — **absent** for mock and local
runs (unpriced is honestly absent, never a fake `0`). Agent loops
report the loop's accumulated tool spend as `tools_cost_usd`.

### Harness tasks in the journal

A task on an agent application you are signed into (a
[harness seat](https://docs.nika.sh/guides/harness-access.md)) runs that application's own tools,
so its journal records what Nika judged rather than each tool call:

* one `permit_checked` per permission the application asked, with its gate
  and the decision `allow`, `deny` or `escalate`. A Codex command that asks
  to leave its sandbox reads `sandbox · command` and always escalates,
  whatever `permits.exec` grants: the run pauses with the command and Codex's
  reason on one sanitized line, and the task's decisions are journaled just
  before `workflow_paused`;
* a turn the application reports as failed (a rejected model, an exhausted
  retry limit) as `task_failed` with `NIKA-1804` (transient, so `retry:` may
  replay it) or `NIKA-1805`, never as a `task_completed` whose output is the
  error text;
* one `agent_image_observed` per image the seat sent, with the digest of the
  received bytes and, under `images: { save: }`, the `saved_path` Nika wrote.

## Replay, never re-execute

Two commands inspect a recorded run. With no path they read the
workspace's latest journal:

```bash theme={"system"}
nika trace replay   # re-render the run, live
nika trace show     # print the final card only
```

`replay` plays the recorded events through the same renderer that drew
the original run: same storyboard and verdict card, with time compressed 6×
by default (`--speed`).
`show` skips the animation and prints the summary. Both are a
**reading** of the file — they do not walk the hash chain.

> [!WARNING]
>
> **Replay = re-render, never re-execute.** Replaying a trace calls no
> model, runs no command, touches no file. Zero tokens, zero effects.
> It is a projection of what already happened, safe to run on any
> machine, any number of times.

## Tamper-evidence · every event, hash-chained

The trace is not just a log — it is a **hash chain**. Every event the
engine emits carries a link over the one before it: task boundaries,
each permit check, every tool call an `agent:` loop makes, the run seal
at the end. Nothing the engine did is off the chain, and nothing can be
edited, reordered, or dropped from the middle without breaking it.

<video autoPlay muted loop playsInline controls poster="/images/posters/trace-proof.png" aria-label="A run's trace drawn as five hash-linked blocks: nika trace verify reports the chain intact, then one byte of line 4 changes in a copy and verify stops at line 5: BROKEN, exit 2" alt="A run's trace drawn as five hash-linked blocks: nika trace verify reports the chain intact, then one byte of line 4 changes in a copy and verify stops at line 5: BROKEN, exit 2">
  <source src="https://mintcdn.com/supernovae-acdf3706/3tG2rJOQxMP3h2LO/videos/trace-proof.webm?fit=max&auto=format&n=3tG2rJOQxMP3h2LO&q=85&s=ecf12428ed814bc82a9a20148f4067c1" type="video/webm" />

  <source src="https://mintcdn.com/supernovae-acdf3706/3tG2rJOQxMP3h2LO/videos/trace-proof.mp4?fit=max&auto=format&n=3tG2rJOQxMP3h2LO&q=85&s=0c0e3e0cd935581a0f503dae7cc8371c" type="video/mp4" />
</video>

**Change one byte, and verify says where.** Each line of a run's trace carries the sha256 of the line before it. `nika trace verify` reads the chain back intact; in a copy with one byte of line 4 changed, it stops at line 5 with `BROKEN` and exit code 2. *A `mock/echo` rehearsal captured from the real CLI on nika 0.121.0; the scan and the moving hashes are illustration.*

```bash theme={"system"}
nika trace verify
```

`verify` walks the chain and then climbs a proof ladder, reporting the
highest tier honestly attained. That is the **proof**, distinct from
`show` / `replay`: those inspect the recorded events; this command
attests the sequence is intact. The tiers:

* **OK** — the links hold; the sequence is intact (`verify` prints
  `OK — N events · chain intact` and the head to compare). An unsigned run
  stops here and says `UNSEALED`.
* **SEALED** — a signature over the whole chain verifies against a
  custody key (the run was signed). `verify` weighs the public keys in the
  order a run signs, the keychain aside, after `--key`: the public half of
  the explicit `NIKA_RUN_KEY_FILE` · `NIKA_RUN_PUB_FILE` pair, when both
  variables are set, then `~/.nika/keys/run-signing.pub`, then the
  retired-key ledger (`~/.nika/keys/retired.pub`). A journal sealed with an
  explicit pair therefore verifies without `--key` wherever the same two
  variables are set.
* **ANCHORED** — a detached sidecar verifies **fully offline** against a
  public transparency log entry + an RFC 3161 timestamp (`nika trace
  anchor` is the opt-in network act that mints it).
* **REPLAYED** — you passed a separately supplied fresh journal; verify
  compares it. The command **never starts** that second run.

`traceVerify` / `nika trace verify` **verifies** an existing seal. It
does not create one. A succeeded run can still be UNSEALED on a keyless
machine. An intact chain is not proof that a human read the output, that
an external API committed, or that the business goal was met.

Refusals name themselves rather than hide in a tier:

| Verdict | Meaning | Exit |
| - | - | - |
| `BROKEN at line N` | the first line whose recorded link no longer matches | 2 |
| `TAMPERED` (`SEAL BURIED`) | lines chained after the seal: appending needs only write access, so this is forgery, never a crash | 2 |
| `SEAL FORGED` | the `run_sealed` signature does not verify against the key | 2 |
| `ANCHOR FORGED` | an anchor sidecar that vouches for nothing | 2 |
| `SEAL UNATTRIBUTABLE` | the seal names a key none of those candidates carries: a missing input, not evidence of forgery. Pass `--key <file.pub>` (on the signing machine, `nika key trust` prints that public key), or set the pair the run was sealed with | 3 |
| `INCOMPLETE` | the journal never reached a terminal frame (a run in flight, or a writer that died): the chain attests every complete line, not the run's outcome | 5 |

`--sealed` and `--anchored` make a missing tier an error (exit 3), a
`--replay` divergence is exit 2, and `--json` prints one machine document
per trace (`verify_version: 1`). `nika trace verify --help` lists the same
exits.

## Why this matters

* **The run is auditable.** Which tasks ran, in what order, how long
  each took, what it cost, which permits were checked: it is all in the
  file, not in someone's scrollback.
* **The run is verifiable.** Every event is hash-chained and the whole
  chain verifies offline (`nika trace verify`) — tamper-evident by
  construction, not by trust.
* **The run is shareable.** Attach the `.ndjson` to a PR or an issue.
  A reviewer replays it locally and sees exactly what you saw, without
  credentials and without re-running anything.
* **The demos are honest.** The replays on [nika.sh](https://nika.sh)
  ("Press play. It really ran.") are exactly these files: recorded runs
  played back through the same renderer, not screenshots and not
  mockups.
* **The run is resumable.** The same file doubles as the checkpoint:
  `nika run --resume <trace>` skips completed work with visible cache
  hits and re-arms a paused human gate. See [Resume a run](https://docs.nika.sh/guides/resume.md).

## Related

* [Reference · CLI](https://docs.nika.sh/reference/cli.md): every `nika run` and `nika trace`
  flag, including `--json` and `--output json` (the typed `outputs:`
  export, a different surface from the event stream).
* [Concepts · Events](https://docs.nika.sh/concepts/events.md): the full event vocabulary and
  the durability model behind it.
* [Concepts · Workflows](https://docs.nika.sh/concepts/workflows.md): how a file becomes the
  executed graph the trace records.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.