feat: add review effort accounting and budget governor

tests/pilot/observability_tests/langfuse_test.py

@@ -159,6 +159,25 @@ def test_batch_without_usage_has_no_generation():
     assert types[0] == "trace-create"
 
 
+def test_batch_exposes_iteration_and_budget_metadata():
+    usage = {
+        **USAGE,
+        "tool_calls": 6,
+        "budget_cap_hit": True,
+        "budget_cap_reason": "max_steps",
+        "iterations": [{"step": 1, "total": 100}],
+    }
+    batch = lt.build_batch(
+        model="headroom/glm-5.2:cloud", **{**BASE, "usage": usage}
+    )
+    metadata = batch[0]["body"]["metadata"]
+    assert metadata["iterations"] == 28
+    assert metadata["tool_calls"] == 6
+    assert metadata["cap_hit"] is True
+    assert metadata["cap_reason"] == "max_steps"
+    assert metadata["iteration_usage"] == [{"step": 1, "total": 100}]
+
+
 def test_trace_carries_repo_pr_session_and_severity_counts():
     batch = lt.build_batch(model="headroom/glm-5.2:cloud", **BASE)
     body = batch[0]["body"]