Budget Governance

OpenMontage enforces spending controls across every pipeline so that generation calls, tool usage, and revisions cannot silently exceed the allocated budget. The cost tracking system records an estimate before any paid work, reserves the amount, and reconciles the actual spend afterward. All values are tracked per project and carried forward in checkpoints.

Estimate-Reserve-Reconcile Lifecycle

Every paid operation follows three explicit steps:

estimate(tool, operation, estimated_usd) → entry_id
        |
reserve(entry_id)          # locks budget
        |
reconcile(entry_id, actual_usd)  # records final spend

• estimate creates a pre-execution record with status estimated and returns an entry_id.
• reserve locks the estimated amount against the remaining budget. It raises ApprovalRequiredError if the amount exceeds the single-action threshold or if a new paid tool is used for the first time. In cap mode it raises BudgetExceededError when usable budget would be exceeded.
• reconcile records the actual cost, clears the reservation, and sets status to completed or failed. A refund helper exists to cancel a reservation without execution.

The system persists every entry to cost_log.json inside the project’s pipeline directory.

Budget Modes

The mode is set in config.yaml under the budget key:

budget:
  mode: warn
  total_usd: 10.00
  reserve_pct: 0.10
  single_action_approval_usd: 0.50

Supported modes:

• observe — records all costs but performs no enforcement.
• warn — logs warnings when an operation would overrun the budget but still allows execution.
• cap — rejects any operation that would exceed the remaining usable budget.

Usable budget is calculated as remaining budget minus the reserve holdback (default 10 %).

Controls

The following controls are available:

• total_usd — overall project budget (default 10.00).
• reserve_pct — safety margin held back from the remaining balance.
• single_action_approval_usd — threshold (default 0.50) that triggers an explicit approval gate.
• require_approval_for_new_paid_tool — first use of any paid tool requires confirmation.

Pipeline manifests can override the default budget for a specific workflow via the orchestration.budget_default_usd field. Cost snapshots are attached to every checkpoint so that later stages and reviewers can see cumulative spend.

Integration with Checkpoints

Checkpoints written after each stage include a cost_snapshot containing total_spent_usd, total_reserved_usd, and budget_remaining_usd. The cost_log.json file accumulates the full audit trail for the project. When a stage produces a proposal_packet, the packet includes an itemized cost_estimate derived from the current tracker state.

See Checkpoint System for how snapshots are validated and carried between stages. For operational details on viewing logs and adjusting limits during a run, see Cost Tracking.