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

# The Ledger

> Every run produces an event ledger — a structured NDJSON log of everything that happened.

# The Ledger

Every run produces an event ledger — a structured NDJSON log of everything that happened. The ledger is the audit trail.

## Where it lives

```
.gump/
  runs/
    index.ndjson
    <run-uuid>/
      manifest.ndjson
      workflow-snapshot.yaml
      state.json
      artifacts/
  worktrees/
    run-<uuid>/
```

## Event types

| Event             | What it records                                   |
| ----------------- | ------------------------------------------------- |
| `run_started`     | Workflow, spec, commit, CLI versions, max\_budget |
| `run_resumed`     | Run ID, resume step, previous status              |
| `step_started`    | Step name, type, agent, task, session mode        |
| `agent_launched`  | CLI, worktree path, prompt hash, session ID       |
| `agent_completed` | Exit code, duration, tokens, cost, session ID     |
| `agent_killed`    | Reason, partial metrics                           |
| `state_updated`   | Key updated                                       |
| `gate_started`    | List of validators                                |
| `gate_passed`     | All checks passed                                 |
| `gate_failed`     | Reason, which gate                                |
| `guard_triggered` | Guard name, reason                                |
| `retry_triggered` | Attempt, overrides                                |
| `hitl_paused`     | Step name                                         |
| `hitl_resumed`    | Action                                            |
| `budget_exceeded` | Scope, max budget, current cost                   |
| `step_completed`  | Status, output summary                            |
| `run_completed`   | Status, duration, total cost                      |

## Reading the ledger

```bash theme={null}
# All events for the last run
cat .gump/runs/*/manifest.ndjson | jq .

# Just the failures
cat .gump/runs/*/manifest.ndjson | jq 'select(.type == "gate_failed")'

# Cost per step
cat .gump/runs/*/manifest.ndjson | jq 'select(.type == "agent_completed") | {step: .step, cost: .cost}'
```

For most use cases, `gump report` is easier. The raw ledger is there when you need fine-grained analysis.

## The causal chain

Every line of code produced by Gump is traceable to its origin:

```
spec → run → step → task → agent → attempt → event
```