feat: add progress-aware run budgets

[efecnc]

Summary

• add a pure, deterministic budget/progress controller for one reasoning run
• keep max_iterations as the absolute emergency LLM-turn ceiling while also tracking wall time, provider-reported tokens, provider retries, and context recoveries
• fingerprint canonicalized tool intents and use typed (tool, error code) root causes instead of parsing tool output prose
• emit a run-scoped non-terminal lifecycle warning before escalation
• stop the third consecutive identical typed root cause as stuck/repeated_root_cause
• stop sustained no-progress runs as stuck/no_progress
• prevent an unresolved warning from becoming completed through prose alone

Default policy

• warning at 80% of a hard budget, four no-progress LLM turns, or the second identical typed root-cause failure
• stuck after eight no-progress turns or the third identical typed root-cause failure
• hard ceilings: configured LLM turns, two hours wall time, five million reported tokens, twelve provider retries, and two context recoveries
• steering/context recovery reset no-progress only; successful new evidence can also clear the repeated-root-cause streak; consumed budgets are never refunded

Regression coverage

• sanitized 50-step failure shape stops on step 3, before the emergency ceiling
• productive 75-step replay remains active
• JSON key order does not create fake tool-intent progress
• independent wall/token/retry/recovery limits are enforced
• terminal decisions are sticky and mutually exclusive
• warning categories re-arm only after relevant progress
• real loop ordering is Started -> Warning -> Terminated(Stuck) with one terminal event
• prose-only completion after an unresolved warning becomes typed Stuck, not Completed

Validation

• cargo fmt --check
• cargo clippy --all-targets --all-features -- -D warnings
• cargo test --all-features (432 library tests passed, 6 existing execution tests ignored; 2 binary tests passed)
• git diff --check

Mandatory risk review

1. Can two terminal outcomes be emitted for one run? No. The controller stores a sticky terminal decision and the existing run wrapper remains the sole lifecycle terminator; integration coverage asserts one terminal event.
2. Can a stale UI command target a replacement run? No new command path is added. Warning events carry the exact existing run_id and chat_id.
3. Can a tool start after steering is accepted but before the instruction enters context? This PR preserves the exact-run safe-boundary steering path and records steering progress only after the instruction is persisted.
4. Can accepted or in-flight composer input be lost? No composer path changes are made.
5. Can one chat provider or fallback settings affect another run? This PR does not mutate provider selection. Run-scoped fallback ownership remains T19.
6. Can replay execute or resend anything? No replay path is added.
7. Can any local inspection log grow without a cap? This PR adds no log sink; it uses the existing capped workspace logger.
8. Can the harness claim completion without a typed terminal reason? No after a budget warning: unresolved no-progress or repeated-root-cause warnings reject prose-only completion and produce typed Stuck.

Integration note

RunLifecycleEvent now includes Warning, and RunBudgetSnapshot carries the independent counters. Strict host parsers must add the warning variant before pinning this commit; that host-side work is T18.

[amazon-q-developer]

Review Complete

I've reviewed all the changes in this PR and found the implementation to be solid and production-ready:

✅ src/agent/budget.rs - New budget controller module with comprehensive test coverage and correct logic
✅ src/agent/mod.rs - Proper integration of budget controller into reasoning loop
✅ src/bus.rs - Well-defined budget types with serialization support
✅ AGENTS.md - Documentation updated to reflect new budget system

No blocking issues found. The code correctly implements:

• Multi-dimensional budget tracking (turns, tokens, time, retries, recoveries)
• Observable progress detection with typed root-cause analysis
• Deterministic state machine with proper terminal state handling
• Warning emissions before exhaustion
• Comprehensive test coverage validating all critical paths

The implementation is ready to merge.

---

You can now have the agent implement changes and create commits directly on your pull request's source branch. Simply comment with /q followed by your request in natural language to ask the agent to make changes.