nika-debugging

# Debugging Nika runs

Every run writes a hash-chained journal to `.nika/traces/`. That journal
is the ONLY truth about what happened — debug from the trace, never from
a memory of the terminal scroll.

## The forensic loop (evidence first)

0. **A failed run already names its trace**: the card's `autopsy:`
   line carries the FULL trace path — start there when you have it.
1. **Locate the run**: `nika trace ls` — age · size · workflow ·
   terminal state (completed/failed/paused) · `★` marks the newest
   trace of each workflow (the resume candidate). Address a trace by
   its store path — `.nika/traces/<name>` — everywhere below (`ls`
   prints bare names; the readers take the path form on every
   version).
2. **Read the card**: `nika trace show <trace>` — the final verdict,
   the waves, per-task outcome. `nika trace replay <trace>` re-renders
   the run live (replay = re-render, NEVER re-execute).
3. **Find the failing task**: `nika trace outputs <trace>` — verb ·
   duration · tokens · a bounded preview per task (full value:
   `nika trace peek`). The first red task is the root; everything
   downstream is fallout.
4. **Decode the finding**: `nika explain NIKA-XXXX` teaches the cause ·
   category · fix-form of any code the trace carries.
5. **Re-audit the file**: `nika check <file>` — a run that failed often
   fails again at check once you know what to look for (a model that no
   longer resolves, a missing env var, a permits violation).
6. **Fix minimally, rerun surgically** (below). Re-check before any
   rerun.

## Prompts and confirm gates (paused OR failed — same answer line)

On a terminal, `nika:prompt` blocks and waits (the run shows as
`paused` in `nika trace ls`). Headless — which is where an agent
lives — a prompt without a `default:` FAILS with
`NIKA-BUILTIN-PROMPT-001` instead. Both states resolve with the same
line:

```
nika run <file> --resume <trace> --answer <task>=<value>
```

Confirm gates take booleans (`--answer approve=true`); every task the
journal already proved is skipped as a visible cache hit, so only the
prompt and its downstream run. Removing a paused trace refuses
without `--force` and names the prompt it would destroy — that
refusal is protecting an answer, not being difficult.

A failed run's card prints its own forensics line (`autopsy:
nika trace peek <trace> <task>`) — start there, it points at the
exact failing task.

## Surgical reruns (never restart what already worked)

- `nika run <file> --from <task-id>` — rerun from one task onward,
  keeping upstream results.
- `nika run <file> --task <task-id>` — rerun exactly one task.
- After an intentional behavior change, refresh the pin:
  `nika test <file> --update` rewrites the golden from an offline mock
  run — never hand-edit a `.golden.json` to make red green.

## Common root causes (check these before anything exotic)

- **Model does not resolve**: `nika check <file> --json` →
  `models_resolve` says whether every `model:` runs in THIS binary;
  `nika catalog` names the env var each provider needs.
- **Missing credential**: secrets ride `${{ secrets.X }}` /
  `${{ env.KEY }}` — the trace shows the task, the shell shows the
  env. `nika doctor` audits the machine side.
- **Timeout too tight**: local providers need `timeout: "300s"` or
  more — thinking models routinely think past 30s.
- **Permits violation**: the run was blocked by its own declared
  boundary — read the finding, then either the task is wrong or the
  boundary is (widen it consciously, never delete it).
- **Cost cap hit**: `--max-cost-usd` blocks BEFORE the call that would
  cross the cap — that is the feature working, not a bug. Raise the
  cap deliberately or shrink the task.

## Tamper evidence

`nika trace verify <trace>` checks the hash chain: any edited,
inserted, dropped or reordered line breaks every hash after it.
Exit 0 intact · 2 broken · 3 unchained (pre-chain journal). Cite the
trace in any report — a verified chain is proof, prose is not.

## Honesty lines

- The trace tells you what the engine did. It cannot tell you WHY a
  provider returned garbage — a provider-side outage or a model
  regression is named as a hypothesis, never asserted as fact.
- Never edit a trace. Never delete a paused trace to "clean up".
- If the binary is missing: `brew install supernovae-st/tap/nika` —
  do not reconstruct runs from memory.