{"record":{"id":"2f097eb2e0ea0c86","repo":"calesthio/OpenMontage","slug":"reservation-of-estimated-2f-exceeds-usable-bud","errorCode":null,"errorMessage":"Reservation of ${estimated:.2f} exceeds usable budget ${self.usable_budget_usd:.2f}","messagePattern":"Reservation of (.+?) exceeds usable budget (.+?)","errorType":"exception","errorClass":"BudgetExceededError","httpStatus":null,"severity":"error","filePath":"tools/cost_tracker.py","lineNumber":149,"sourceCode":"                    f\"single-action threshold ${self.single_action_approval_usd:.2f}\"\n                )\n\n        # Check new paid tool approval\n        if self.require_approval_for_new_paid_tool and estimated > 0:\n            if entry[\"tool\"] not in self._approved_tools:\n                if self.mode != BudgetMode.OBSERVE:\n                    raise ApprovalRequiredError(\n                        f\"First paid use of tool {entry['tool']!r} requires approval\"\n                    )\n\n        # Check budget\n        if estimated > self.usable_budget_usd:\n            message = (\n                f\"Reservation of ${estimated:.2f} exceeds usable budget \"\n                f\"${self.usable_budget_usd:.2f}\"\n            )\n            if self.mode == BudgetMode.CAP:\n                raise BudgetExceededError(message)\n            if self.mode == BudgetMode.WARN:\n                entry[\"budget_warning\"] = True\n                entry[\"budget_warning_message\"] = message\n\n        entry[\"status\"] = EntryStatus.RESERVED.value\n        entry[\"reserved_usd\"] = estimated\n        entry[\"timestamp\"] = self._now()\n        self._save()\n\n    def approve_tool(self, tool: str) -> None:\n        \"\"\"Mark a tool as approved for paid operations.\"\"\"\n        self._approved_tools.add(tool)\n        self._save()\n\n    def reconcile(self, entry_id: str, actual_usd: float, success: bool = True) -> None:\n        \"\"\"Reconcile actual spend after tool execution.\"\"\"\n        entry = self._find(entry_id)\n        entry[\"status\"] = EntryStatus.COMPLETED.value if success else EntryStatus.FAILED.value","sourceCodeStart":131,"sourceCodeEnd":167,"githubUrl":"https://github.com/calesthio/OpenMontage/blob/95e1c3d0ab93482159818560f6a8c8e866b9139f/tools/cost_tracker.py#L131-L167","documentation":"BudgetExceededError raised by CostTracker.reserve in CAP mode when estimated_usd exceeds usable_budget_usd (total budget minus already-spent/reserved amounts). CAP mode enforces the ceiling hard; in WARN mode the same condition only stamps budget_warning fields on the entry and continues. This is the tracker's real 'out of money' guard.","triggerScenarios":"reserve(entry_id) with mode == CAP and estimated > usable_budget_usd. Happens when cumulative reservations approach budget_total_usd and a new action does not fit in the remainder.","commonSituations":"Long batch runs where many small costs accumulate until the remainder is smaller than the next action's estimate; budget_total_usd set too low for the workload; stale reserved entries never released eating usable budget.","solutions":["Release or settle stale RESERVED entries you no longer need so usable_budget_usd is recomputed from actual spend.","Raise budget_total_usd to match the workload.","Switch mode to WARN if you want warnings instead of hard stops (entry gets budget_warning flags instead of an exception).","Reduce the action's cost (cheaper model, shorter output) or skip it until other reservations complete."],"exampleFix":"# before\ntracker.reserve(entry_id)  # CAP mode, estimate 0.80 > usable 0.50 -> BudgetExceededError\n\n# after\nfrom tools.cost_tracker import BudgetMode\ntracker.mode = BudgetMode.WARN\ntracker.reserve(entry_id)  # warns (entry['budget_warning']=True) instead of raising","handlingStrategy":"try-catch","validationCode":"def fits_budget(tracker, entry_id: str) -> bool:\n    entry = next(e for e in tracker.entries if e[\"id\"] == entry_id)\n    return entry[\"estimated_usd\"] <= tracker.usable_budget_usd","typeGuard":null,"tryCatchPattern":"from tools.cost_tracker import BudgetExceededError\n\ntry:\n    tracker.reserve(entry_id)\nexcept BudgetExceededError:\n    skip_or_queue_action()  # do not proceed with the paid call","preventionTips":["Settle or release RESERVED entries promptly so usable budget is accurate.","Monitor usable_budget_usd before each expensive step in batch loops.","Size budget_total_usd from expected run length; use WARN mode when a hard stop is unacceptable."],"tags":["budget","cost-tracking","cap","policy"],"backgroundTag":null,"analyzedSha":"95e1c3d0ab93482159818560f6a8c8e866b9139f","analyzedAt":"2026-08-15T06:31:20.014Z","schemaVersion":2},"datasetVersion":"2026-08-15T22:17:37.221Z"}