Skip to main content

​
The Ledger

Every run produces an event ledger — a structured NDJSON log of everything that happened. The ledger is the audit trail. It records what ran, when, with which agent, what it cost, and what the outcome was.

​
Where it lives

.gump/
  runs/
    index.ndjson                    ← index of all runs
    <run-uuid>/
      manifest.ndjson               ← events for this run
      workflow-snapshot.yaml         ← the workflow YAML as it was at run time
      context-snapshot.json          ← resolved config and context
      state-bag.json                ← final state bag
      artifacts/                    ← plan JSONs, artifact texts, review JSONs
The manifest.ndjson file contains one JSON object per line, one event per line.

​
Event types

EventWhat it records
run_startedWorkflow name, spec path, initial commit, agent CLI versions, max_budget
step_startedStep name, agent, output mode, item (if foreach), session mode
group_startedGroup name, foreach ref, parallel flag, item count
agent_launchedCLI command, worktree path, prompt hash, session ID
agent_completedExit code, duration, tokens, cost, session ID, artifact refs
agent_killedStep, reason (guard/timeout/circuit_breaker), partial metrics
state_bag_updatedKey that was updated
state_bag_scope_resetStart of a group retry
gate_passedWhich checks passed
gate_failedWhich check failed, stderr output
guard_triggeredGuard name, reason
retry_triggeredStrategy used, attempt number
hitl_pausedStep name
hitl_resumedAction taken
budget_exceededScope, max budget, current cost
step_completedStatus (pass, fail, fatal)
group_completedStatus
circuit_breakerReason
run_completedStatus, total duration, total cost

​
Reading the ledger

The ledger is plain NDJSON — you can read it with jq, grep, or any tool that handles newline-delimited JSON: 
# 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 — it reads the ledger and presents a summary. The raw ledger is there when you need fine-grained analysis.

​
The causal chain

Every event in the ledger carries enough context to trace back to its origin: 
spec → run → step → item → agent → attempt → event
You can follow this chain from any line of code in the final diff all the way back to the spec that requested it, the step that produced it, the agent that wrote it, and the attempt that succeeded.