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.

​
Where it lives

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

​
Event types

EventWhat it records
run_startedWorkflow, spec, commit, CLI versions, max_budget
run_resumedRun ID, resume step, previous status
step_startedStep name, type, agent, task, session mode
agent_launchedCLI, worktree path, prompt hash, session ID
agent_completedExit code, duration, tokens, cost, session ID
agent_killedReason, partial metrics
state_updatedKey updated
gate_startedList of validators
gate_passedAll checks passed
gate_failedReason, which gate
guard_triggeredGuard name, reason
retry_triggeredAttempt, overrides
hitl_pausedStep name
hitl_resumedAction
budget_exceededScope, max budget, current cost
step_completedStatus, output summary
run_completedStatus, duration, total cost

​
Reading the ledger

# 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