Skip to main content
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):
--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 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, with each event’s fields abridged. Every line carries chain, the hash that links it to the line before:
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 event kinds of engine are listed in Concepts · Events. 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. A file that declares run.access or run.reasoning also journals what it asked and what its route did. access_requirement, the declaration, rides workflow_started and the terminal event of each infer: or agent: task. access_selection rides that terminal event once the task reached its route: for the model, the effort and a declared service tier, the value asked, the value sent and the value read back, kept apart (Harness access). A file that declares neither journals neither.

Harness tasks in the journal

A task on an agent application you are signed into (a harness seat) 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:
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.
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.

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.

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: --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 (“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.
  • Reference · CLI: 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: the full event vocabulary and the durability model behind it.
  • Concepts · Workflows: how a file becomes the executed graph the trace records.