fix: `run --max-turns` charges completed steps, not retried attempts

AN
14h ago
+689-56

Issue for this PR

Closes #1808

Type of change

  • Bug fix
  • New feature
  • Refactor / code improvement
  • Documentation

What does this PR do?

run --max-turns N charged a turn when a step started. After a mid-stream failure the session retries the step, up to 5 times, and each retry starts again. So every failed attempt cost a turn, and a run could stop with "reached N assistant turns limit" before N steps had completed. This affects every provider, most visibly slow or flaky model servers.

Now a turn is charged when a step finishes, and a step may start only while fewer than N steps have completed. --max-turns N still means N completed assistant steps.

Before → after (--max-turns 1; the first stream fails with a retryable rate-limit error and the retry succeeds):

  • Before: the retry counts as turn 2. The run aborts as budget-exhausted and exits 1 without an answer.
  • After: the failed attempt is free. The retry completes as 1 turn, prints its answer, and the run exits 0.

Details:

  • Compaction steps are still never charged.
  • Harness-injected steps are real assistant steps and are still charged when they finish: the idle-done challenge, the continuation and the silent-turn reply.
  • The committed-answer echo and the one best-effort reply after a budget abort keep their allowances.
  • A step still open when compaction replaces it, or cut short by a context-overflow error, is still charged, as on main and whichever event arrives first. So overflow-and-compact cycles stay bounded. A step that a retry or an idle session closes is free.
  • Trade-off: a flaky provider can now spend up to 6 calls (1 + 5 retries) per allowed turn. The processor retry cap, after which the error ends the run nonzero, and the time budget bound a step that never completes.
  • Not changed: an overflow rejected before any step starts can loop through compaction without limit, as it already could on main. Tracked in #1813.
  • Sweep: the turn count is read only by the run command's budget checks. Events, trace metadata and the TUI carry the configured limit, not the count. The help text now says "completed" turns.

How did you verify your code works?

  • New CLI subprocess tests, turn-budget-retry.test.ts:
    • The real processor, with a stream that fails mid-step and then succeeds, costs 1 turn and exits 0.
    • 6 attempts that all fail end with the provider error: no budget abort, no re-prompt.
    • Endless attempts are still ended by the time budget.
    • A step cut short by overflow costs its turn. This test fails if overflow charging is removed.
    • A compaction step after the budget is used is neither charged nor stopped.
  • Processor test: every stream breaks mid-step, so the step is retried exactly 5 times (6 calls, no step finish) and then fails. Loosening the cap fails the test.
  • Unit tests cover charging on finish, overflow charging (counted once, never for a compaction step) and the compaction exclusion. Existing budget fixtures now finish their steps.
  • The new turn-budget tests fail on main (c00b2dc10de) and pass here. Typecheck and the marker check pass.
  • Locally, the only failures in the run CLI suites are time-budget tests that also fail on main on this machine under load.

Local review: no P0–P2 findings at head db16e073ef6.

Cost side effects

None. No model calls, queries or resources are added.

Screenshots / recordings

Not a UI change.

Checklist

  • I have tested my changes locally
  • I have not included unrelated changes in this PR
  • I checked for cost side effects (model calls, queries or cloud resources that grow with user data) and described them, or wrote "none"

🤖 Generated with Claude Code