Work within a spend limit

You have a number in mind and you do not want to find out you passed it afterwards. This guide is about the mechanisms that hold a ceiling, in the order they fire — one of them before any money is spent at all.

The flag

stella --spend-limit 2.00 run "port the utils module to the new API"

--spend-limit is a global flag, so it can go on either side of the subcommand — but the habit of putting it first is a good one, because it reads as a property of the whole invocation, which is what it is.

Set it once for a shell or a CI job instead:

export STELLA_SPEND_LIMIT=5

Where the abort lands

This is the part worth trusting, because it determines whether a tripped spend limit leaves you with work or with wreckage.

The meter is checked between steps and stages — never in the middle of a tool call. An abort therefore never leaves a half-applied edit, a partially written file, or a tool whose side effects landed but whose result never made it back into the transcript. Work already committed to disk stays; nothing is rolled back.

The exit code is 1, the same as any other failure. If you need to distinguish the spend limit stopped this from this failed, read the JSON:

stella --spend-limit 2.00 run --output-format json "…" | jq '{status, cost_usd, verdict}'

The gate that fires before you spend

A spend limit stops a run partway. The scope review stops it before the first edit, which is usually the outcome you actually wanted.

When a plan's blast radius crosses any of three thresholds, stella pauses and shows you the plan:

Every comparison is a strict >, so a plan sitting exactly on a threshold passes without a gate. At the card, a approves, t trims to the largest prefix that would not have tripped review, x aborts — and anything longer than one of those words is read as what you want changed, sending the plan back to the planner with your note attached.

What the money is actually spent on

Before tuning anything, know the shape of the bill — most attempts to economize target the wrong stage.

Three consequences follow, and they are most of what you need:

1. The worker's output price dominates. Moving the worker to a cheaper model changes the bill several-fold. Moving the verifier barely changes it at all.
2. A flagship verifier is cheap insurance. One verifier call is a few thousand input tokens and under a thousand out. Keep it in a different family than the worker.
3. --test-command is the strongest cost flag on the CLI. It arms the deterministic flip oracle, so most runs finish on evidence alone with the verifier skipped entirely — and it skips the witness-author call too.

# Cheapest correct shape: deterministic oracle armed, hard ceiling on top.
stella --spend-limit 1.50 run --test-command "cargo test -p api" \
  "add cursor pagination to /orders"

The multipliers

A ceiling only helps if you know what is pushing against it.

When the transcript outgrows the window

A long run's cost is not only what it does — it is how much conversation it carries while doing it. When the transcript approaches the compaction budget (150,000 tokens by default), stella compacts it and keeps going, rather than failing or silently truncating.

Compaction applies four mechanisms, least-lossy first:

1. Dedup. A byte-identical tool output appearing more than once keeps only its earliest copy; later ones become a pointer to it.
2. Supersession. When the same call ran twice with identical input, only the latest result reflects current state — the older ones are stale by construction and get stubbed.
3. Aging. Still over budget, large old outputs are middle-out truncated to head plus tail. The head carries the tool's framing (a PASSED/FAILED line, file headers) and the tail carries the errors, so what survives is the part worth reading.
4. Eviction. Only then are the oldest large tool outputs replaced with a stub — and a result whose call is still the most recent one is never evicted.

The system message and the latest user message are never touched.

If a conversation is still over budget after all four passes, an overflow summarizer runs — a real extra model call, recorded at --call-seq 1 for that step. Seeing those in stella inspect is the sign a run's transcript, not its work, is what got expensive.

Picking the number

Set the spend limit by observation, not by intuition. Run the class of task once unbounded, read what it cost, then set a ceiling with headroom:

stella run "the representative task"           # observed mode
stella stats --format text                    # what it actually cost
stella --spend-limit 2.00 run "the next one"   # now with a ceiling

The number to steer on over time is $/resolved, not sticker price — a cheap model that needs three attempts is not cheap. The Observatory tracks it per model, and Examples & recipes has complete configurations at four different price points.

Next