fix: correct stale Sphinx cross-refs in errors.py and add 5% boundary test

- BudgetExhausted and BudgetConfigError docstrings referenced
  firewall.budgets.BudgetManager (pre-split path); now point to
  firewall.budget_manager.BudgetManager
- Add test_suggested_mode_boundary_exactly_five_percent_is_summary_not_handle_only
  to confirm 5% exactly lands in the summary bucket, not handle_only;
  guards against a future < → <= comparator change

Author: dgenio

src/agent_kernel/errors.py

@@ -50,7 +50,7 @@ class FirewallError(AgentKernelError):
 
 
 class BudgetExhausted(AgentKernelError):
-    """Raised when a :class:`~agent_kernel.firewall.budgets.BudgetManager` has
+    """Raised when a :class:`~agent_kernel.firewall.budget_manager.BudgetManager` has
     no remaining cross-invocation context budget.
 
     Distinct from :class:`FirewallError`: this error fires *before* the
@@ -61,7 +61,7 @@ class BudgetExhausted(AgentKernelError):
 
 
 class BudgetConfigError(AgentKernelError):
-    """Raised when a :class:`~agent_kernel.firewall.budgets.BudgetManager` is
+    """Raised when a :class:`~agent_kernel.firewall.budget_manager.BudgetManager` is
     constructed with invalid parameters, or asked to allocate/record/release
     a negative amount.
 

tests/test_firewall.py

@@ -534,3 +534,16 @@ async def test_suggested_mode_boundary_exactly_twenty_percent_floors_summary() -
     await bm.record_usage(800)
     assert bm.suggested_mode("raw") == "summary"
     assert bm.suggested_mode("table") == "summary"
+
+
+@pytest.mark.asyncio
+async def test_suggested_mode_boundary_exactly_five_percent_is_summary_not_handle_only() -> None:
+    # 5% exactly sits in the 5–20% summary bucket because the handle_only
+    # guard is strictly-less-than: (0.05 < 0.05) is False.  A future change
+    # from `< 0.05` to `<= 0.05` would silently misplace this boundary.
+    bm = BudgetManager(total_budget=1000)
+    await bm.record_usage(950)  # 5% remaining
+    assert bm.suggested_mode("raw") == "summary"
+    assert bm.suggested_mode("table") == "summary"
+    assert bm.suggested_mode("summary") == "summary"
+    assert bm.suggested_mode("handle_only") == "handle_only"  # never relaxes