Every conversation is a durable session: transcript, model-facing context, tool calls, usage ledger, plan, todos, and episode state persist in SQLite and survive restarts. This page covers the session lifecycle, persistence, resume, concurrent sessions, and budgets.
$BONSAI_HOME/bonsai.db (default ~/.bonsai/bonsai.db) — SQLite in WAL
mode, permissions hardened (0700 home, 0600 database). Ordered
migrations run at open; before applying pending migrations to an existing
database, bonsai snapshots it to $BONSAI_HOME/backups/ and a failed
migration restores the snapshot automatically. See
Compatibility for the upgrade/rollback contract.
What a session snapshot holds: the rendered transcript, the model-facing
context messages (resume-authoritative), tool calls with args/results/diffs,
compaction and episode records, read evidence, the per-turn usage ledger,
verification and self-review runs, plan and todos, and a full-text-searchable
copy of plain messages (powering /search and recall’s query mode).
Verification snapshots include each logical check’s execution and delivery
workspace bindings, attempt timestamps, failure-signature history, final
result, and typed skip/block reason. An in-flight verification restored after
a crash or resume is converted to typed interrupted evidence rather than
left running.
Secrets never enter the database — credentials are stored by
reference only.
lifecycle_only identity for peers; authorization and model selection
classify it as provider_probe. The first meaningful user, provider, tool,
or plan activity atomically promotes the same identity to task.
Startup-only snapshots cannot receive task, todo, verification, review,
or episode evidence and do not enter task-quality metrics./resume ordering stays content-recency-based. An
active-run timer accumulates foreground execution time for the
session-time budget; a crashed segment is recovered only up to its last
heartbeat.set_session_title (also an
episode boundary hint); otherwise the first
user prompt seeds a derived title./quit, /clear, or /new complete the session.
/clear//new rotate to a fresh row (new cache key, cleared episodes and
plan canvas); crash leftovers are promoted to interrupted at next boot,
excluding rows with a fresh heartbeat (that’s what makes concurrent
sessions safe). Terminal reasons — including typed budget exhaustion — are
recorded on the row, not reported as generic failures.
Retention removes only a newly classified, cleanly completed unused identity
without peer, authorization, recovery, or saved-plan evidence. Crashes and
ambiguous historical rows remain available for diagnosis; migration never
deletes them.bonsai -c resumes the latest session for the project; bonsai -c <id>
a specific one. In the TUI, /sessions lists, /resume [id] resumes,
/forget <id> deletes, /search <query> searches message history.
Normal session lists and latest-session resume include task sessions only.
/sessions all shows diagnostic classifications, including startup/configuration
identities and legacy_unclassified rows whose history cannot prove task work.
An explicit session id remains available for inspecting or resuming retained
diagnostic history.BONSAI_PROVIDER on resume; --model can still
override for that run), and restores its conversation cache key so the
provider-side prompt cache stays warm.Multiple bonsai processes can work in one project root concurrently:
peers tool lists live peers, sends bounded,
redacted, rate-limited messages (≤6,000 chars, ≤30/hour), registers a
one-shot wake-when-done on another session (mutual waits are refused;
auto-wakes are hop- and rate-limited to prevent loops), and takes advisory
claims on work areas. Message delivery uses durable per-consumer
leases, so a crash never drops or double-delivers a message./peers shows a live read-only view. Per-session changed-file records
attribute concurrent edits correctly (the self-review pass subtracts
peer-attributed paths from its diff).Hard limits are off by default; enable presets in /settings or pass
headless flags (flags override saved values for that run). Session soft
alerts ship conservative defaults — $5 exact cost, 10M billed tokens, 250
provider turns, 2h active time — that warn before submit once reached
(“Continue once”, or raise/disable a threshold under /settings → Session
alerts). The defaults apply until you save a budget of your own, and a saved
budget always wins, including an explicit off. When any turn lacks pricing,
the cost alert is disabled and reads unknown while the token, turn, and
time alerts keep warning.
Per-run (reset each run): max turns, run time, generation (per
provider attempt), output (streamed chars per attempt), tool time (per
tool call — a stalled call is cancelled without killing the run).
Per-session (cumulative across resumes, consuming the persisted ledger —
including output from failed provider retries): session turns,
session output, session compute (the selected clock — active
compute by default, so permission and question waits do not exhaust it),
session cost.
max_turns, session_cost, provider_rate_limit, …) in
SQLite, and — in headless JSON — emits status: "budget_exhausted" with a
typed budget_exhaustion object. See Headless mode.max_run_seconds stays a
per-run wall deadline under either policy, so excluding waits can never
let a run continue unbounded. BONSAI_TIMING_POLICY=wall_clock opts into
charging the waits too; see Runtime timing./usageEvery provider response is one ledger turn: lane (parent / subagent / self-review / compaction), tokens (prompt, completion, cache read/write), cost and a no-cache baseline cost (their difference is the cache saving), finish reason, latency and time-to-first-token, cache-route telemetry (expected vs actual cache-read percent, prefix hashes, rewrite events), and inspection counters. Subagent turns keep their own lane and per-turn model identity while folding into session totals.
/usage — the cross-project analytics dashboard (activity, models, cost,
sessions, tools, cache tabs plus a heatmap)./perf (alias /cost) — the current session’s performance/usage report./ctx — where the context window itself is going; see
Context management.Cost math is honest about unknowns: turns without pricing flag the session’s cost as inexact, and dashboard totals are floors, with unknown-cost turns counted separately.
| Concern | Location |
|---|---|
| Database, migrations, backups | src/storage/mod.rs, migrations/ |
| Session rows & resume | src/storage/sessions.rs, src/tui/run/persistence.rs |
| Snapshot writer | src/session_persist.rs |
| Peers & workspace leases | src/peer.rs, src/storage/peers.rs, src/storage/workspace_locks.rs |
| Budgets | src/run_budget.rs |
| Usage ledger & dashboard | src/agent/usage_ledger.rs, src/storage/usage_stats.rs |