Budget

Swarmie budget settings come from [budget] in config.toml (crates/core/src/config/toml_types.rs) and are enforced per session by BudgetEvaluator (crates/core/src/budget/evaluator.rs).

Config Shape

[budget]
hard_cap = 25.0
soft_cap = 20.0
warning_threshold_pct = 75

Field	Type	Meaning
`hard_cap`	float (USD)	Hard stop threshold. New turns are blocked once projected/recorded cost reaches this value.
`soft_cap`	float (USD)	Warning-only threshold. Turns continue but emit warning state once crossed.
`warning_threshold_pct`	integer (0-100)	Percent warning threshold, evaluated against `hard_cap`.

Runtime Behavior

Budget decisions are evaluated before each user turn (crates/core/src/submission/op_handlers.rs):

Allow: turn proceeds.
AllowWithWarning: turn proceeds and emits a warning message.
Block: turn is rejected with budget.session_hard_cap_exceeded.

After each completed turn, cumulative session cost is recorded from Event::TurnComplete.cost (crates/core/src/submission/turn_lifecycle.rs).

Important Details

Soft-cap and warning thresholds do not block turns.
Hard cap is terminal for the session budget state unless explicitly overridden in code.
If only soft_cap is set (no hard_cap), soft-cap warnings still work.
If no [budget] section is set, budget enforcement is disabled.

Example Workflow

Session starts at $0.00.
Cost crosses warning_threshold_pct or soft_cap and Swarmie emits a warning.
Session cost reaches hard_cap and subsequent turns are blocked.