> ## 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.

# Resume a run

> The trace is the checkpoint: nika run --resume skips completed work with visible cache hits, and a human gate can pause a run durably.

A long run dies at task 7 of 9 — laptop lid, a provider hiccup, a kill.
(Ctrl-C is not a death: in-flight work settles and is counted, unstarted
tasks are cancelled, the trace seals with `workflow_cancelled`, the run exits
130, and `--resume` picks up from it like any other.)
With most tools that is 7 tasks of tokens re-spent. With Nika the run's
own trace is the checkpoint: **`--resume` re-executes the workflow,
skipping every task whose recorded work is still valid** (ADR-099).
No daemon, no run store, no new artifact — the reader of a file you
already have.

That sentence is the whole architecture, so it deserves saying plainly:
durable-execution systems anchor recovery in standing infrastructure —
a database, an embedded log server, or a managed cloud — and pay for it
with author-facing rules (deterministic code, side effects quarantined
into steps, versioning APIs, replay-test suites). Nika anchors recovery
in the hash-chained trace every run already writes. **No server, no
database — the trace is the checkpoint**: readable with `cat`, diffable
with git, owned by you. Two hashes decide skip-or-rerun; recorded work
replays from the trace; everything else honestly re-executes. No
determinism is ever demanded of your workflow.

## Record, then resume

```yaml release-notes.nika theme={"system"}
# Collect commits, draft notes, stamp a file.
nika: release-notes

model: mock/echo                       # swap for ollama/llama3.2:3b or any provider

permits:
  exec: ["printf"]                     # the only program either task launches

tasks:
  collect:
    exec:
      command: ["printf", "feat: resume\nfix: deadline"]

  draft:
    with:
      commits: ${{ tasks.collect.output }}
    infer:
      prompt: "Draft release notes from: ${{ with.commits }}"
      max_tokens: 400

  stamp:
    after:
      draft: success
    exec:
      command: ["printf", "stamped"]

outputs:
  notes: "${{ tasks.draft.output }}"
```

Redirecting stdout into `.nika/traces/...` fails **before Nika starts**
if the folder is missing. Create it, write a named journal, resume that
same path:

```bash theme={"system"}
mkdir -p .nika/traces
nika run release-notes.nika --json > .nika/traces/release-notes.ndjson
nika run release-notes.nika --resume .nika/traces/release-notes.ndjson
```

A run without `--json` still writes an automatic timestamped journal
under `.nika/traces/`; `nika trace verify` with no path reads the
latest. The copyable sequence above is the named file the `--resume`
line uses.

Resume from the file you just wrote:

```text theme={"system"}
$ nika run release-notes.nika --resume .nika/traces/release-notes.ndjson
rehearsal: mock/echo answers by echoing the prompt — not a real answer · a real one: `--model <provider/model>` with its key, or `--access <seat>` (nika doctor lists them)
  🦋 nika · release-notes · 3 tasks
     permits ✓ declared boundary · exec outside the fs bounds

  ↷  collect  cache hit (resume)
  ↷  draft    cache hit (resume)
  ↷  stamp    cache hit (resume)
  3 tasks · 3 waves · 0 retries
  ── 3/3 done · unmetered · elapsed 0.0s ─────────────────────────
    wrote .nika/traces
  explore: nika run release-notes.nika --json > run.ndjson · nika trace outputs run.ndjson
    trace: .nika/traces/2026-10-24T14-41-33Z-7f92.ndjson · 8 events · chain 06df5663424624864947af11390e8fe1b3ca45a875d9475c7fd96ca604ad89b3

  resumed · 3 skipped (cache hit) · 0 ran live
```

Every skip is **visible** — a `cache hit` line in the render, a
`task_cache_hit` event in the new trace, and the summary counts skipped
vs live. A resumed run never pretends work happened silently.

> [!NOTE]
>
> A trace recorded by an engine version without resume keys is not an
> error: `--resume` prints a notice and runs everything live.

## The skip rule · two hashes, both must match

A task skips **iff** the trace holds its completed record and

1. the **task definition** hashes the same (the verb body, `with:`,
   `extract:`, `retry:` / `on_error:`, `when:`, `for_each:` — as now
   written), and
2. the **resolved inputs** hash the same (what its `${{ }}` references
   actually resolved to — upstream outputs, `inputs`, `const`, `secrets`).

Edit a prompt → that task re-runs. Pass a different `--var` → the tasks
that consume it re-run, and the mismatch cascades exactly as far as the
data flows — untouched sibling branches still skip:

```text theme={"system"}
$ nika run brief.nika --var topic="local-first AI" --resume .nika/traces/brief.ndjson
  resumed · 1 skipped (cache hit) · 0 ran live

$ nika run brief.nika --var topic="sovereign memory" --resume .nika/traces/brief.ndjson
  resumed · 0 skipped (cache hit) · 1 ran live
```

An `infer:` / `agent:` task that matches replays its recorded output —
that is the point: crash-resume without re-spending tokens. There are no
determinism rules, no replay constraints, no workflow versioning:
durability is the engine's problem, never yours. A task that does not
match simply re-runs live, side effects included.

> [!WARNING]
>
> **The honest limit — at-least-once, not exactly-once.** A task whose
> **definition and resolved inputs still hash the same** is skipped. Edit
> the verb, change `--var` / `inputs`, or pass `--from` and that work
> runs again — "completed" is not a forever lock. A crash *in the middle*
> of a side effect can also double-fire it on re-run. Make external
> effects idempotent via their own arguments, or fence the node with
> `--from` discipline.

## `--from` · force a re-run the hashes cannot see

Some changes are invisible to hashing: a rotated secret, external state,
an `infer:` output you want re-rolled. `--from <task_id>` forces that
task **and its transitive downstream** to re-run even on a match —
upstream tasks still cache-hit:

```text theme={"system"}
$ nika run release-notes.nika --resume .nika/traces/release-notes.ndjson --from draft
rehearsal: mock/echo answers by echoing the prompt — not a real answer · a real one: `--model <provider/model>` with its key, or `--access <seat>` (nika doctor lists them)
  🦋 nika · release-notes · 3 tasks
     permits ✓ declared boundary · exec outside the fs bounds

  ↷  collect  cache hit (resume)
  ✔  draft    infer · mock/echo · untrusted input from collect  0ms
  ✔  stamp    exec · printf · untrusted input from stamp  9ms
  3 tasks · 3 waves · 0 retries · 10 tok
  ── 3/3 done · unpriced (1 call) · elapsed 0.0s ─────────────────
    wrote .nika/traces
    said "mock(echo) · Draft release notes from: feat…"
    see it whole: nika trace outputs
    rehearsal · a mock model echoed the prompt — not a real answer
  explore: nika run release-notes.nika --json > run.ndjson · nika trace outputs run.ndjson
    trace: .nika/traces/2026-10-24T14-41-38Z-11c8.ndjson · 12 events · chain 9b58dd4428449b29161cea04aac7a7eb55f61e861b5fb201217de9a545c36289

  resumed · 1 skipped (cache hit) · 2 ran live
```

An unknown task id is refused before the run, like an unknown `--var` key.

> [!WARNING]
>
> **Secrets participate by name, never by value** — a trace carries no
> secret-derived material, so a *rotated* secret does not invalidate the
> cache. That is the one sharp edge: after a rotation, force the
> affected node with `--from`.

## The durable human gate · pause and answer

A [`nika:prompt`](https://docs.nika.sh/concepts/verbs#invoke-call-a-builtin-or-mcp-tool) task waits on a human. **At a
terminal, the gate asks you directly** (confirm `[y/N]` · choice by
number or value · input verbatim) and the run continues through the
same verified resume path. Anywhere no human can answer (a pipe · CI ·
an agent · `--json`) with no usable `default:`, the run does not hang
and does not fail — it **pauses durably**: the trace records a
`workflow_paused` event with the prompt payload, the process exits with
code **4**, and the frame prints the exact resume line (your
`--var`/`--model` included). Pre-answer in one pass with
`--answer <task>=<value>` at launch.

<video autoPlay muted loop playsInline controls poster="/images/posters/approval-gate.png" aria-label="gated-ship.nika at a terminal asks Ship this build to production? [y/N] and y lets ship run; in CI the same run pauses with exit code 4 and prints one resume line, and running that line reuses build and ships" alt="gated-ship.nika at a terminal asks Ship this build to production? [y/N] and y lets ship run; in CI the same run pauses with exit code 4 and prints one resume line, and running that line reuses build and ships">
  <source src="https://mintcdn.com/supernovae-acdf3706/FqLt1ba-IKwd_as0/videos/approval-gate.webm?fit=max&auto=format&n=FqLt1ba-IKwd_as0&q=85&s=973149bebb8840f201e08f0cf056e1f4" type="video/webm" />

  <source src="https://mintcdn.com/supernovae-acdf3706/FqLt1ba-IKwd_as0/videos/approval-gate.mp4?fit=max&auto=format&n=FqLt1ba-IKwd_as0&q=85&s=80da6d73c34e6674d2247128c658251f" type="video/mp4" />
</video>

**Nothing ships without a yes.** At a terminal, the `gated-ship.nika` below asks `Ship this build to production? [y/N]`, and `y` lets `ship` run. Where nobody can answer, as in CI, the same run pauses durably, exits 4 and prints the one line that resumes it. Run that line: `build` is a cache hit, the answer rides in `--answer approve=true`, and `ship` runs. *Every terminal line is captured from the real CLI on nika 0.121.0, offline and with no model; the door, its light, the keypress, the paste and the CI frame are illustration.*

```yaml gated-ship.nika theme={"system"}
# Build, ask a human, ship only on yes.
nika: gated-ship

permits:
  exec: ["printf"]                     # build + ship · the argv form is the provable one
  tools: ["nika:prompt"]               # the human gate · default-deny once permits: is present

tasks:
  build:
    exec:
      command: ["printf", "build ok"]

  approve:
    after:
      build: success
    invoke:
      tool: "nika:prompt"
      args:
        message: "Ship this build to production?"

  ship:
    with:
      approved: ${{ tasks.approve.output }}
    when: "${{ with.approved == true }}"
    exec:
      command: ["printf", "shipped"]
```

```bash theme={"system"}
nika run gated-ship.nika --json > .nika/traces/gated-ship.ndjson
echo $?   # 4 · paused — not a failure, but non-zero so `&& next` stops here
```

The paused trace carries everything needed to pick the run back up, on
the same machine, by a different process:

```json the workflow_paused event (one line of the trace · reformatted · trimmed) theme={"system"}
{"kind": "workflow_paused", "fields": [
  {"key": "workflow", "value": "gated-ship"},
  {"key": "task",     "value": "approve"},
  {"key": "mode",     "value": "confirm"},
  {"key": "note",     "value": "awaiting a `nika:prompt` answer — resume with `--resume <trace> --answer <task>=<value>`"},
  {"key": "message",  "value": "Ship this build to production?"},
  {"key": "approval_minted_at_ms", "value": 1792852902444},
  {"key": "approval_ttl_seconds",  "value": 900},
  {"key": "status",   "value": "paused"},
  {"key": "cause",    "value": "human_gate"}]}
```

> [!WARNING]
>
> **An answer binds only within 15 minutes of the pause.** Each approval is
> a fresh-consent ticket (`approval_ttl_seconds: 900`). Resume later with
> `--answer` and the stale answer is not bound: the gate asks again, the run
> pauses again (exit 4) and prints a **new** trace path. Answer that new
> pause within 15 minutes, or pre-answer at launch with `--answer`.

Resume with the answer bound to the task id via `--answer` (repeatable):

```text theme={"system"}
$ nika run gated-ship.nika --resume .nika/traces/gated-ship.ndjson --answer approve=true
  🦋 nika · gated-ship · 3 tasks
     permits ✓ declared boundary · exec outside the fs bounds

  ↷  build    cache hit (resume)
  ✔  approve  invoke · nika:prompt  0ms
  ✔  ship     exec · printf · untrusted input from ship  8ms
  3 tasks · 3 waves · 0 retries
  ── 3/3 done · unmetered · elapsed 0.0s ─────────────────────────
    wrote .nika/traces
  explore: nika run gated-ship.nika --json > run.ndjson · nika trace outputs run.ndjson
    trace: .nika/traces/2026-10-24T14-41-46Z-365b.ndjson · 14 events · chain 913b840f94ec7bd8623185cfb239fb36aecd4bf307d1b49a471e1230c0f7ecd2

  resumed · 1 skipped (cache hit) · 2 ran live
```

The value follows the prompt's `mode:`. **`confirm` wants a boolean**
(`--answer approve=true` / `=false` — a refusal is a value, and the
`when:` gate downstream decides what happens with it). `input` takes a
string, `choice` one of the declared choices. Like `--var`, the value
parses as JSON when it parses.

Resumed **without** an answer, a `--json` run pauses again — idempotent,
exit 4 every time, so a poller can retry harmlessly. A poller that relays
a human's answer must resume from the newest trace each pause prints and
deliver the answer within 15 minutes of that pause; past the window the
gate asks again, as above. Resumed interactively (a human at the
terminal), the prompt simply asks.

A late answer, captured on 0.123.0: a second paused run, journaled as
`gated-late.ndjson`, answered fifteen minutes and forty seconds after its
pause:

```text theme={"system"}
$ nika run gated-ship.nika --resume .nika/traces/gated-late.ndjson --answer approve=true
  🦋 nika · gated-ship · 3 tasks
     permits ✓ declared boundary · exec outside the fs bounds

  ↷  build    cache hit (resume)
  3 tasks · 3 waves · 0 retries
  ── 1/3 done · unmetered · elapsed 0.0s ─────────────────────────
    wrote .nika/traces

  ◇ paused · awaiting an answer for `approve`
    answer: nika run --answer approve=true FILE  (boolean true/false, not yes)
  explore: nika run gated-ship.nika --json > run.ndjson · nika trace outputs run.ndjson
    trace: .nika/traces/2026-10-24T14-57-36Z-5cdd.ndjson · 6 events · chain 7dcc81726d3a356014a541bae0ba75b02d354da4d31a157c36d498b60d3b42fc
    resume: nika run gated-ship.nika --resume .nika/traces/2026-10-24T14-57-36Z-5cdd.ndjson --answer approve=true · or false

  resumed · 1 skipped (cache hit) · 0 ran live
```

Run the printed `resume:` line within 15 minutes and `ship` runs.

## Exit codes

| Exit | Meaning |
| - | - |
| `0` | Run completed |
| `1` | Run executed and a task failed unrecovered |
| `2` | Validation findings — the file never ran (also: a trace whose chain is broken) |
| `3` | Environment error (also: unknown `--var` / `--from` key, a trace written by another project) |
| `4` | **Paused** on a human gate — resume with `--resume <trace> --answer <task>=<value>` within 15 minutes of the pause |
| `130` | Cancelled by the operator (Ctrl-C · SIGTERM) — the trace is sealed and resumable |

## Related

* [Concepts · Traces](https://docs.nika.sh/concepts/traces.md): the NDJSON recorder this rides —
  record, replay, share.
* [Concepts · Workflows](https://docs.nika.sh/concepts/workflows.md): `--var` inputs (a changed
  input re-runs exactly the tasks that consume it).
* [Guides · Testing](https://docs.nika.sh/guides/testing.md): the offline golden gate for the
  same files.

## Further reading

The design has a lineage, and naming it beats pretending novelty:

* **Build Systems à la Carte** — Mokhov, Mitchell & Peyton Jones, ICFP
  2018 ([doi:10.1145/3236774](https://doi.org/10.1145/3236774)). The
  formal frame for hash-keyed skip-or-rerun: `--resume` is a build
  system's verifying trace applied to a workflow DAG.
* **Durable Functions: Semantics for Stateful Serverless** — Burckhardt
  et al., OOPSLA 2021
  ([doi:10.1145/3485510](https://doi.org/10.1145/3485510)). The
  semantics of replay-based durable execution — and of the determinism
  obligation that comes with it, which content-addressed resume
  structurally avoids.
* **Nextflow** — Di Tommaso et al., Nature Biotechnology 2017
  ([doi:10.1038/nbt.3820](https://doi.org/10.1038/nbt.3820)). Scientific
  computing proved content-addressed `-resume` a decade ago; its
  ecosystem calls it the single most-loved feature.

## A trace is not a bearer artifact

The opening frame binds the trace to the project that wrote it
(`project_root_fingerprint`). `--resume` judges that binding FIRST: a
trace copied from another project refuses with exit `3` and one typed line
on the `--json` stream — « a trace is not a bearer artifact: resume it from
the project that wrote it, or run the workflow afresh here ». An older trace
with no fingerprint is no claim.

`--resume-unverified` waives the chain check for a trace whose journal was
edited or truncated. It does NOT replay a human's yes: every recorded
`nika:prompt` decision re-asks under the opt-out (a decision is a
credential, and the chain that bound it to this run is waived), and the door
says the project binding is a recorded field the waived chain no longer
protects.


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