cdx-manager 0.24.9 → 0.25.0

package/README.md

@@ -4,7 +4,7 @@
 
 <br clear="left"/>
 
-[![License](https://img.shields.io/badge/license-MIT-4C8BF5)](LICENSE) ![Version](https://img.shields.io/badge/version-v0.24.9-4C8BF5) ![Python](https://img.shields.io/badge/python-3.9%2B-3776AB?logo=python&logoColor=white)
+[![License](https://img.shields.io/badge/license-MIT-4C8BF5)](LICENSE) ![Version](https://img.shields.io/badge/version-v0.25.0-4C8BF5) ![Python](https://img.shields.io/badge/python-3.9%2B-3776AB?logo=python&logoColor=white)
 
 **The right AI coding account, when you need it.** CDX Manager keeps your Codex and Claude accounts in separate profiles, shows which ones have quota, and helps you pick the next usable session from your terminal.
 
@@ -59,6 +59,16 @@ cdx run --continue-run RUN_ID --cwd /path/to/repo --prompt "Fix the remaining te
 
 Conservative assumption: a continuation requires a finished Claude or Codex run, a locally available provider transcript, and recorded model and effort settings. Missing runs, profiles, expired sessions, and unavailable settings produce a clear error; the caller can retry without `--continue-run` for a cold run. `--failover` and `--isolate-workspace` cannot be combined with continuation. Capacity recovery and provider model fallback are disabled for continuations so they cannot silently switch model or account. Provider cache retention remains provider-controlled, so resuming does not guarantee a cache hit.
 
+## Run costs and budgets
+
+`cdx history --json` includes nullable `cost_usd` for each entry, estimated from its observed usage and serving model using the same table and `CDX_TOKEN_PRICES` overrides as `cdx stats`. Unknown prices or usage stay `null`.
+
+```bash
+cdx run work --cwd /path/to/repo --prompt "Fix the tests" --budget 2.50 --json
+```
+
+`--budget` stops a run once its measured estimated cost reaches the USD amount, including with `--detach` and `--continue-run`. A budget stop exits with code 125 and reports `error.code: "budget_exceeded"` and `error.spent_usd`. Detached callers read the final result through `cdx run-status` or `cdx run-report`. Usage arrives in provider updates, so the estimate can overshoot; unknown usage or prices cannot trigger a budget stop. See the [budget contract](docs/cli.md#run-budgets) for details.
+
 ## Codex model capacity recovery
 
 `cdx run` (including `--detach`) automatically recovers from Codex's "Selected model is at capacity" failure. It retries the same prompt, profile, and model after 1 and 2 seconds, then tries the profile's `fallback_model` list in configured order, removing duplicates. Configure alternatives with `cdx set work --fallback-model MODEL_A,MODEL_B`.

package/VERSION

@@ -1 +1 @@
-0.24.9
+0.25.0

package/changelogs/CHANGELOGS_0_25_0.md

@@ -0,0 +1,17 @@
+# CDX Manager 0.25.0
+
+Release date: 2026-10-31
+
+This release adds per-run cost estimates and enforces estimated USD budgets. (#71)
+
+## Run costs and budgets
+
+- Include nullable `cost_usd` estimates in history and run results, using observed usage, the serving model, cache token rates, and the same pricing table and `CDX_TOKEN_PRICES` overrides as stats. Unknown usage or prices remain `null`. (#71)
+- Add `cdx run --budget USD` to stop a run when its measured estimated spend reaches the limit. Retries, model recovery, and account failover share the run budget; a budget stop terminates the provider process tree and prevents further recovery or failover. (#71)
+- Support budgets for detached and continued runs. A continuation starts a fresh budget that excludes earlier turns; detached results remain available through `cdx run-status` and `cdx run-report`. (#71)
+- Report budget stops with exit code `125`, `error.code: "budget_exceeded"`, and `error.spent_usd`; include `cost_usd` and `budget_usd` in final results. Estimates depend on reported usage and known prices, so delayed updates can cause overshoot and unknown costs cannot trigger a stop. (#71)
+
+## Maintenance
+
+- Record tray companion checksums for v0.24.9. (`eb4de92877c91f339426b344f9f242bdede02eec`)
+- Record release archive checksums for v0.24.9. (`afecbfdcf4b999663cd6937955349824728f621e`)

package/changelogs/CHANGELOGS_UNRELEASED.md

@@ -0,0 +1,7 @@
+# Unreleased
+
+## Run costs and budgets
+
+- Add nullable `cost_usd` to JSON history entries using the same observed usage, model pricing, and price overrides as stats.
+- Add `cdx run --budget USD` to stop on measured estimated spend with exit code 125, `budget_exceeded`, and `error.spent_usd` in the final JSON. Share the budget across recovery attempts and failover; support detached runs and fresh budgets for continued runs without charging earlier turns.
+- Document unknown usage/prices and delayed provider reporting, including possible budget overshoot. Cover pricing, unknown costs, validation, live process termination, Claude transcript accumulation, continuation boundaries, and detached supervision in tests.

package/checksums/release-archives.json

@@ -672,6 +672,17 @@
         "x86_64-pc-windows-msvc": "6df3f25ab6a9aa02a45aa6f90f95c3484553b248175394af9ecfd12668479281",
         "x86_64-unknown-linux-musl": "ea867d352a18db59e882d6abbdbafa61b54fbec7fafa66746852696cf18cd6c5"
       }
+    },
+    "v0.24.9": {
+      "github_tarball_sha256": "1bf646b5f6dc5b3fa9ba99a7736d62fc0170469cbb6bf6617124dfb134cbbea7",
+      "github_zip_sha256": "b921117dfd70beb48e8688d94706f755714a4eb826a94dc4b73ef250e646324e",
+      "tray_assets": {
+        "aarch64-apple-darwin": "378b8b9d85159263f9ce4a130ad0c67d5f142b43609b3719be0664c9b3125fed",
+        "aarch64-unknown-linux-musl": "49f9f5e1d0a352935a9e7c738150d36f679b22c66b389c937124e01bf6d954ac",
+        "x86_64-apple-darwin": "40a12abb38b8b4ef61c110f6426847b190cb9dd7f146d8f33f3abf0e5b3d8488",
+        "x86_64-pc-windows-msvc": "21dfebd0265bd8705d381517357cd8166cb0e2da37b27ed3e3485c892d9289ee",
+        "x86_64-unknown-linux-musl": "8477262e55f31ee2217382048b967846478a34f222beeb4242fa9c4c2942f747"
+      }
     }
   }
 }

package/docs/cli.md

@@ -56,7 +56,7 @@
 | `cdx agents [--max-age-hours N] [--json]` | Each session's last known agent state (working, waiting, done, failed, limit, ended), waiting first; records older than N hours (default 24) are dropped. See [Agent state](sessions-and-notifications.md#agent-state) |
 | `cdx next [--json] [--refresh]` | Select the best next assistant using the same priority logic as `cdx status` |
 | `cdx select --provider PROVIDER [--min-reasoning-effort minimal\|low\|medium\|high\|xhigh] [--min-power minimal\|low\|medium\|high\|xhigh] [--require-ready] [--refresh] --json` | Select a suitable session for headless automation |
-| `cdx run [session] --cwd PATH (--prompt-file PATH\|--prompt TEXT\|--prompt-file -) [--provider PROVIDER] [--model MODEL] [--kind assistant\|code-review\|retro] [--reasoning-effort minimal\|low\|medium\|high\|xhigh] [--power minimal\|low\|medium\|high\|xhigh] [--permission MODE] [--timeout-seconds N] [--label TEXT] [--max-parallel N] [--continue-run RUN_ID] [--detach] [--failover] [--refresh] --json` | Run one headless task and return a stable JSON result; `--detach` returns the `run_id` at launch without waiting, `--failover` continues the task on the next account when this one hits its rate limit (with `--detach` too: the detached cdx child applies it and the run's `occupancies` record each move), `--prompt-file -` reads the prompt from stdin, `--label` names the run in `cdx runs`, `--max-parallel N` (default `CDX_MAX_RUNS`; unset, invalid, 0 or negative means no limit) refuses to start with `too_many_runs` when N runs are already running, `--kind` (default `assistant`) labels the run record and `code-review` adds a review report to its final payload |
+| `cdx run [session] --cwd PATH (--prompt-file PATH\|--prompt TEXT\|--prompt-file -) [--provider PROVIDER] [--model MODEL] [--kind assistant\|code-review\|retro] [--reasoning-effort minimal\|low\|medium\|high\|xhigh] [--power minimal\|low\|medium\|high\|xhigh] [--permission MODE] [--timeout-seconds N] [--budget USD] [--label TEXT] [--max-parallel N] [--continue-run RUN_ID] [--detach] [--failover] [--refresh] --json` | Run one headless task and return a stable JSON result; `--detach` returns the `run_id` at launch without waiting, `--failover` continues the task on the next account when this one hits its rate limit (with `--detach` too: the detached cdx child applies it and the run's `occupancies` record each move), `--prompt-file -` reads the prompt from stdin, `--label` names the run in `cdx runs`, `--max-parallel N` (default `CDX_MAX_RUNS`; unset, invalid, 0 or negative means no limit) refuses to start with `too_many_runs` when N runs are already running, `--kind` (default `assistant`) labels the run record and `code-review` adds a review report to its final payload |
 | `cdx run-report <run_id> --json` | Full report, transcript metadata, and final payload for a run; `final_message` is the run's last assistant message, read from Claude's `result` envelope or Codex's last `agent_message` (null when neither exists) |
 | `cdx run-status <run_id> --json` | Status of one run by id |
 | `cdx run-tail <run_id> [--lines N] --json` | Last lines of a run's own output, while it is still running or after it finished |
@@ -245,6 +245,16 @@ Known headless and completed interactive token usage is persisted in launch hist
 
 Continuation errors are `continue_run_not_found` (unknown parent), `continue_run_mismatch` (another or missing profile/provider), `continue_run_unavailable` (unfinished or unsupported run, expired transcript, or unavailable settings), and `continue_run_settings_mismatch` (changed model/effort or incompatible flags). Callers may start a normal run after a refusal by omitting `--continue-run`.
 
+#### Run budgets
+
+`cdx run --budget USD` accepts a finite positive amount in US dollars. It uses the same token pricing function, cache rates, and `CDX_TOKEN_PRICES` overrides as `cdx stats`. The supervisor checks reported stdout usage and the exact provider conversation transcript every 250 ms while waiting, and checks again at completion. Claude's transcript messages are summed; continuation measurements subtract the transcript snapshot taken before this run. Earlier turns do not consume the new budget. Measured costs from retries, model recovery, and account failover share the same run budget.
+
+At or above the limit, cdx terminates the provider process tree, skips further recovery/failover, records the run as `failed`, and exits with **125**. The final JSON has `ok: false`, `exit_code: 125`, `error.source: "cdx"`, `error.code: "budget_exceeded"`, and `error.spent_usd` with the measured estimated spend across attempts. `cost_usd` repeats that amount and `budget_usd` records the requested limit. Normal results also include nullable `cost_usd` for their observed usage and `budget_usd` (`null` without the flag).
+
+With `--detach`, the launch still exits successfully and includes `budget_usd`; cdx always uses its own child supervisor for budgeted runs, including when native background delegation is enabled. Inspect `cdx run-status RUN_ID --json` or `cdx run-report RUN_ID --json` for the child's final payload and budget error. `--continue-run` starts a fresh budget for the new run, including in detached mode.
+
+Conservative assumption: this is a stop based on observed, priceable usage, not a prepaid billing limit. Provider updates can arrive late or only at completion, and termination can take time, so actual spend can exceed the amount. Missing usage, missing continuation boundaries, mixed/unobserved models, and unknown prices are not treated as free tokens and cannot trigger the budget; their estimated cost stays `null`. Supply a `CDX_TOKEN_PRICES` override for a model missing from the table. Existing profile-level `cdx set --budget` settings remain the provider-native Claude cap and apply independently.
+
 Every usage record, whichever path produced it, uses one set of definitions:
 
 | Field | Meaning |
@@ -267,6 +277,8 @@ History and stats text show `cache 72 %` beside tokens, or `cache n/d` for unkno
 
 Ranking on the raw total would put a session that mostly replayed a cache above one that spent far more on generation, because cache reads are typically the overwhelming majority of tokens consumed while costing a fiftieth of an output token.
 
+`cdx history --json` includes `cost_usd` on every entry, calculated when read using the current stats price table and overrides. Missing or untrusted usage and unknown serving models/prices yield `null`, never a fabricated zero. Cache reads, writes (including one-hour TTL), and output use the same rates as stats.
+
 The **`USD~`** column turns that into money for runs whose serving model cdx recorded. It prices each token class directly using the built-in model table. To customize prices: set `CDX_TOKEN_PRICES` to a JSON object mapping model id to dollars per million tokens to override the built-in table, whose last review date is printed with the totals. A run whose model cdx never saw stays unpriced rather than being charged at a default tier, and the totals line says how many runs were actually priced.
 
 The table requires `input` and `output` prices in USD per million tokens and accepts an optional `cache_read` price in the same units. Without it, cache reads cost 0.1x input; cache writes assume 1.25x input. GPT-6.1 Sol and Claude Opus 5.5 use 0.05x cache reads, while Claude Fable/Mythos 5.1 use 0.025x. Both `COST~` and `USD~` honor those rates. `CDX_TOKEN_PRICES` replaces the supplied model row: a two-field override keeps the legacy 0.1x fallback; include `cache_read` to override it (including zero).

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "cdx-manager",
-  "version": "0.24.9",
+  "version": "0.25.0",
   "description": "Terminal session manager for Codex and Claude accounts.",
   "license": "MIT",
   "author": "Alexandre Agostini",

package/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "cdx-manager"
-version = "0.24.9"
+version = "0.25.0"
 description = "Terminal session manager for Codex and Claude accounts."
 readme = "README.md"
 requires-python = ">=3.9"

package/src/cli_args.py

@@ -5,6 +5,7 @@ Split out of cli_commands.py: pure input-parsing layer (no command execution),
 imported back there and used by the handlers.
 """
 
+import math
 from datetime import datetime, timedelta
 
 from .config import (
@@ -47,7 +48,7 @@ CAN_RESUME_USAGE = "Usage: cdx can-resume <name> [--conversation <id>] [--json]"
 SESSIONS_USAGE = "Usage: cdx sessions [--all] --json"
 SELECT_USAGE = "Usage: cdx select --provider PROVIDER [--min-reasoning-effort minimal|low|medium|high|xhigh] [--min-power minimal|low|medium|high|xhigh] [--require-ready] [--refresh] --json"
 NEXT_USAGE = "Usage: cdx next [--json] [--refresh]"
-RUN_USAGE = "Usage: cdx run [session] (--cwd|--dir) PATH (--prompt-file PATH|--prompt TEXT|--prompt-file -) [--provider PROVIDER] [--model MODEL] [--kind assistant|code-review|retro] [--reasoning-effort minimal|low|medium|high|xhigh] [--power minimal|low|medium|high|xhigh] [--permission review|default|auto|full|workspace-write|read-only|danger-full-access] [--network-access] [--isolate-workspace] [--timeout-seconds N] [--label TEXT] [--max-parallel N] [--continue-run RUN_ID] [--detach] [--failover] [--refresh] --json"
+RUN_USAGE = "Usage: cdx run [session] (--cwd|--dir) PATH (--prompt-file PATH|--prompt TEXT|--prompt-file -) [--provider PROVIDER] [--model MODEL] [--kind assistant|code-review|retro] [--reasoning-effort minimal|low|medium|high|xhigh] [--power minimal|low|medium|high|xhigh] [--permission review|default|auto|full|workspace-write|read-only|danger-full-access] [--network-access] [--isolate-workspace] [--timeout-seconds N] [--budget USD] [--label TEXT] [--max-parallel N] [--continue-run RUN_ID] [--detach] [--failover] [--refresh] --json"
 RUN_JSON_REQUIRED = "cdx run: --json is required."
 RUN_TARGET_REQUIRED = "cdx run: specify a session name or --provider PROVIDER."
 RUN_SESSION_PROVIDER_CONFLICT = "cdx run: cannot specify both a session name and --provider."
@@ -425,6 +426,17 @@ def _parse_timeout_seconds(value, usage=RUN_USAGE):
     return parsed
 
 
+def _parse_run_budget(value):
+    try:
+        amount = float(value)
+        if not math.isfinite(amount) or amount <= 0:
+            raise ValueError
+        return amount
+    except (TypeError, ValueError) as error:
+        raise CdxArgumentError("cdx run: --budget must be a finite positive USD amount.",
+                               code=ARG_CODE_OUT_OF_RANGE, arguments=["--budget"]) from error
+
+
 def _parse_run_timeout_seconds(value):
     try:
         return _parse_timeout_seconds(value, RUN_USAGE)
@@ -539,6 +551,7 @@ def cdx_schema():
                 "provider_start_failed",
                 "provider_failed",
                 "provider_timeout",
+                "budget_exceeded",
                 "run_cancelled",
                 "too_many_runs",
                 "failover_exhausted",
@@ -671,6 +684,7 @@ def _parse_run_args(args):
         "--power": {"key": "power", "type": "str", "default": None},
         "--permission": {"key": "permission", "type": "str", "default": None, "transform": _normalize_run_permission},
         "--timeout-seconds": {"key": "timeout_seconds", "type": "str", "default": None, "transform": _parse_run_timeout_seconds},
+        "--budget": {"key": "budget", "type": "str", "default": None, "transform": _parse_run_budget},
         "--detach": {"key": "detach", "type": "bool", "default": False},
         "--network-access": {"key": "network_access", "type": "bool", "default": False},
         "--isolate-workspace": {"key": "isolate_workspace", "type": "bool", "default": False},
@@ -727,6 +741,7 @@ def _parse_run_args(args):
         "kind": parsed["kind"],
         "model": parsed["model"],
         "permission": parsed["permission"],
+        "budget": parsed["budget"],
         "timeout_seconds": parsed["timeout_seconds"],
         "detach": parsed["detach"],
         "network_access": parsed["network_access"],

package/src/commands/runs.py

@@ -25,7 +25,7 @@ from ..cli_args import (
 from ..cli_helpers import API_SCHEMA_VERSION, _json_failure, _json_success, _write_json
 from ..config import split_extra_args
 from ..errors import CdxError
-from ..interactive_usage import MEASURED_KEYS, extract_interactive_usage, usage_delta
+from ..interactive_usage import MATCH_CONVERSATION_ID, MEASURED_KEYS, extract_interactive_usage, usage_delta
 from ..provider_background import (
     BACKGROUND_PATH_CDX,
     BACKGROUND_PATH_PROVIDER,
@@ -58,7 +58,7 @@ from ..run_failover import (
     looks_model_at_capacity,
 )
 from ..run_registry import RunRegistry, build_code_review_report, final_message
-from ..run_usage import empty_usage, extract_run_conversation_id, extract_run_observation
+from ..run_usage import empty_usage, estimate_cost, extract_run_conversation_id, extract_run_observation, token_prices
 from ..session_ranking import FACTOR_DESCRIPTIONS, rank_sessions, selection_policy
 from ..status_view import _now_timestamp, _priority_reset_timestamp
 
@@ -204,6 +204,7 @@ def _detached_child_argv(parsed, prompt_path, session_name, cwd):
     # from the package root, so a relative "--cwd ." would resolve there.
     argv = ["run", session_name, "--cwd", cwd, "--prompt-file", prompt_path]
     for flag, key in (
+        ("--budget", "budget"),
         ("--continue-run", "continue_run"),
         ("--model", "model"),
         ("--kind", "kind"),
@@ -563,6 +564,28 @@ def _observe_headless_usage(session, run_info, baseline=None):
     return observation
 
 
+def _budget_observation(session, paths, baseline):
+    observation = _observe_headless_usage(session, paths, baseline if session["provider"] == "codex" else None)
+    identifier = (extract_run_conversation_id(session["provider"], paths.get("stdout_path"))
+                  or ((session.get("conversation") or {}).get("id")
+                      if session["provider"] == "claude" or session.get("continue_run") else None))
+    if not identifier:
+        return observation
+    usage, path, match, model = extract_interactive_usage(
+        session["provider"], session.get("authHome"), conversation_id=identifier)
+    if usage is None or match != MATCH_CONVERSATION_ID:
+        return observation
+    if baseline is not None:
+        before, before_path, _match, _model = baseline
+        comparable = (before and path == before_path
+                      and all((usage.get(key) is None) == (before.get(key) is None) for key in MEASURED_KEYS))
+        usage = usage_delta(usage, before, provider=session["provider"]) if comparable else None
+    if usage is not None:
+        return {**observation, "usage": usage, "usage_model": model, "provider_transcript_path": path,
+                "provider_transcript_match": match}
+    return observation
+
+
 def _continue_run_session(parsed, ctx):
     """Resolve only the parent's profile and exact persisted conversation."""
     previous = _run_registry(ctx).get(parsed["continue_run"])
@@ -624,6 +647,7 @@ def handle_run(rest, ctx):
     detached_run_id = os.environ.pop(DETACHED_RUN_ID_ENV, None) or None
     try:
         parsed = _parse_run_args(rest)
+        budget_prices = token_prices()[0] if parsed.get("budget") is not None else None
         session = _continue_run_session(parsed, ctx) if parsed.get("continue_run") else None
         if session:
             if session.get("enabled", True) is False:
@@ -738,7 +762,7 @@ def handle_run(rest, ctx):
             launch = None
             # A provider's own background agent has no cdx process watching it,
             # so nothing could fail it over; --failover keeps the in-house child.
-            if not parsed.get("continue_run") and not parsed.get("isolate_workspace") and not parsed.get("network_access") and not parsed.get("failover") and supports_native_background(
+            if not parsed.get("budget") and not parsed.get("continue_run") and not parsed.get("isolate_workspace") and not parsed.get("network_access") and not parsed.get("failover") and supports_native_background(
                 run_session.get("provider"),
                 env=ctx.get("env"),
                 spawn_sync=ctx.get("spawn_text"),
@@ -773,6 +797,7 @@ def handle_run(rest, ctx):
         failover_error_code = None
         recovery_events = []
         attempt = 0
+        spent_usd = 0.0
         models = capacity_models(run_session)
         model_index = 0
         capacity_retries = 0
@@ -781,7 +806,20 @@ def handle_run(rest, ctx):
             baseline = extract_interactive_usage(
                 run_session["provider"], run_session.get("authHome"),
                 conversation_id=(run_session.get("conversation") or {}).get("id"),
-            ) if parsed.get("continue_run") and run_session["provider"] == "codex" else None
+            ) if parsed.get("continue_run") and (run_session["provider"] == "codex" or parsed.get("budget")) else None
+            attempt_cost = None
+            budget_observation = None
+
+            def check_budget(paths, session=run_session, before=baseline, already_spent=spent_usd):
+                nonlocal attempt_cost, budget_observation
+                observation = _budget_observation(session, paths, before)
+                cost = estimate_cost(observation["usage"], observation["usage_model"], budget_prices)
+                if cost is not None:
+                    if attempt_cost is None or cost >= attempt_cost:
+                        attempt_cost = cost
+                        budget_observation = observation
+                return attempt_cost is not None and already_spent + attempt_cost >= parsed["budget"]
+
             run_info = _run_headless_provider_command(
                 run_session,
                 cwd=cwd,
@@ -790,8 +828,11 @@ def handle_run(rest, ctx):
                 timeout_seconds=parsed.get("timeout_seconds"),
                 spawn=ctx.get("spawn_headless") or ctx.get("spawn"),
                 run_id=run_id,
+                **({"budget_check": check_budget} if parsed.get("budget") is not None else {}),
             )
-            observation = _observe_headless_usage(run_session, run_info, baseline)
+            observation = _observe_headless_usage(run_session, run_info, baseline if run_session["provider"] == "codex" else None)
+            if run_info.get("budget_exceeded") and budget_observation is not None:
+                observation = budget_observation
             run_info = {**run_info, **observation,
                         "parent_run_id": parsed.get("continue_run"),
                         "conversation_id": extract_run_conversation_id(run_session.get("provider"), run_info.get("stdout_path"))
@@ -800,6 +841,10 @@ def handle_run(rest, ctx):
                         "reasoning_effort": _launch_power(run_session),
                         "effective_model": (run_session.get("launch") or {}).get("model"),
                         "recovery_events": recovery_events}
+            cost = estimate_cost(observation["usage"], observation["usage_model"], budget_prices)
+            spent_usd += max(attempt_cost or 0.0, cost or 0.0)
+            if parsed.get("budget") is not None and (run_info.get("budget_exceeded") or spent_usd >= parsed["budget"]):
+                run_info.update(budget_exceeded=True, returncode=125, cost_usd=spent_usd)
             ctx["service"]["record_launch_history"](run_session["name"], {
                 "status": "success" if run_info.get("returncode") == 0 else "failed",
                 "action": "run",
@@ -809,7 +854,7 @@ def handle_run(rest, ctx):
                 "exit_code": run_info.get("returncode"),
                 **run_info,
             })
-            if parsed.get("continue_run"):
+            if run_info.get("budget_exceeded") or parsed.get("continue_run"):
                 break
             if looks_model_at_capacity(run_session.get("provider"), run_info):
                 event = {"reason": "model_at_capacity", "attempt": attempt,
@@ -934,7 +979,10 @@ def handle_run(rest, ctx):
             )
             _write_json(ctx, final_payload)
             return 0
-        if failover_error_code == "capacity_recovery_exhausted":
+        if run_info.get("budget_exceeded"):
+            failover_error_code = "budget_exceeded"
+            message = "Run exceeded its estimated USD budget."
+        elif failover_error_code == "capacity_recovery_exhausted":
             message = "Codex model capacity recovery exhausted its retry, model, or profile budget."
         elif failover_error_code == "failover_exhausted":
             message = f"Every eligible session was rate limited: {', '.join(attempted)}."
@@ -952,7 +1000,7 @@ def handle_run(rest, ctx):
             run_session,
             run_info=run_info,
             error=error,
-            error_source="provider",
+            error_source="cdx" if run_info.get("budget_exceeded") else "provider",
             # Running out of accounts is a different outcome from the task
             # failing, and a caller has to be able to branch on which happened.
             error_code=failover_error_code or (
@@ -962,7 +1010,7 @@ def handle_run(rest, ctx):
         )
         registry.finish(
             run_id,
-            status="timed_out" if run_info.get("timed_out") else "failed",
+            status="timed_out" if run_info.get("timed_out") and not run_info.get("budget_exceeded") else "failed",
             final_payload=final_payload,
             run_info=run_info,
             error=final_payload.get("error"),

package/src/commands/status.py

@@ -672,6 +672,7 @@ def handle_history(rest, ctx):
     entries = ctx["service"]["get_launch_history"](parsed["name"], limit=limit)
     entries = _filter_history_period(entries, parsed["period"])
     entries = [{**entry, "parent_run_id": entry.get("parent_run_id"),
+                "cost_usd": estimate_cost(entry.get("usage"), entry.get("usage_model")) if is_vouched(entry.get("usage")) else None,
                 "usage": {**entry["usage"], "cache_hit_ratio": cache_hit_ratio(entry["usage"], provider=entry.get("provider")) if is_vouched(entry["usage"]) else None}
                 if isinstance(entry.get("usage"), dict) else entry.get("usage")} for entry in entries]
     if has_period and not parsed["summary"]:

package/src/provider_runtime.py

@@ -8,6 +8,7 @@ import signal
 import subprocess
 import sys
 import threading
+import time
 import uuid
 from datetime import datetime, timezone
 
@@ -1204,7 +1205,7 @@ def _read_permission_denials(stdout_path):
 
 
 def _run_headless_provider_command(session, cwd=None, env_override=None, initial_prompt=None,
-                                   timeout_seconds=None, spawn=None, run_id=None):
+                                   timeout_seconds=None, spawn=None, run_id=None, budget_check=None):
     spawn = spawn or subprocess.Popen
     spec = _build_headless_launch_spec(
         session,
@@ -1262,6 +1263,7 @@ def _run_headless_provider_command(session, cwd=None, env_override=None, initial
     child = None
     timed_out = False
     cancelled = False
+    budget_exceeded = False
     with open(paths["stdout_path"], "w", encoding="utf-8", errors="replace") as stdout_file, \
             open(paths["stderr_path"], "w", encoding="utf-8", errors="replace") as stderr_file:
         options = {k: v for k, v in spec.get("options", {}).items() if k not in ("stdio", "stdout", "stderr")}
@@ -1290,7 +1292,23 @@ def _run_headless_provider_command(session, cwd=None, env_override=None, initial
         # this supervisor and keep its run "running" forever.
         previous_handlers = _route_termination_to_interrupt()
         try:
-            if timeout_seconds is None:
+            if budget_check is not None:
+                deadline = time.monotonic() + timeout_seconds if timeout_seconds is not None else None
+                while True:
+                    if budget_check(paths):
+                        budget_exceeded = True
+                        _terminate_child_tree(child)
+                        break
+                    remaining = deadline - time.monotonic() if deadline is not None else None
+                    if remaining is not None and remaining <= 0:
+                        raise subprocess.TimeoutExpired(command, timeout_seconds)
+                    try:
+                        child.wait(timeout=min(0.25, remaining) if remaining is not None else 0.25)
+                        budget_exceeded = budget_check(paths)
+                        break
+                    except subprocess.TimeoutExpired:
+                        continue
+            elif timeout_seconds is None:
                 child.wait()
             else:
                 child.wait(timeout=timeout_seconds)
@@ -1337,6 +1355,7 @@ def _run_headless_provider_command(session, cwd=None, env_override=None, initial
         "pid": getattr(child, "pid", None),
         "returncode": returncode,
         "timed_out": timed_out,
+        "budget_exceeded": budget_exceeded,
         "permission_denials": (
             _read_permission_denials(paths["stdout_path"])
             if session.get("provider") == PROVIDER_CLAUDE else []

package/src/run_command.py

@@ -4,7 +4,7 @@ import sys
 from .cli_args import ARG_CODE_INVALID_VALUE
 from .errors import CdxArgumentError, CdxError
 from .provider_runtime import headless_permission_disables_network
-from .run_usage import empty_usage, extract_run_observation
+from .run_usage import empty_usage, estimate_cost, extract_run_observation
 
 PROMPT_STDIN = "-"
 
@@ -172,6 +172,7 @@ def run_launch_payload(api_schema_version, parsed, session, artifacts, cwd=None,
         "parent_run_id": parsed.get("continue_run"),
         "conversation_id": conversation_id or run_conversation_id(session),
         "detached": True,
+        "budget_usd": parsed.get("budget"),
         "session": session.get("name") if session else None,
         "provider": session.get("provider") if session else parsed.get("provider"),
         "model": parsed.get("model") or ((session.get("launch") or {}).get("model") if session else None),
@@ -235,11 +236,14 @@ def run_result_payload(api_schema_version, ok, parsed, session, run_info=None,
         "stderr_path": run_info.get("stderr_path"),
         "usage": usage,
         "usage_model": usage_model,
+        "cost_usd": run_info.get("cost_usd", estimate_cost(usage, usage_model)),
+        "budget_usd": parsed.get("budget"),
         "warnings": warnings,
         "error": None if ok else {
             "source": error_source or "cdx",
             "code": error_code or "cdx_error",
             "message": message,
+            **({"spent_usd": run_info.get("cost_usd")} if error_code == "budget_exceeded" else {}),
             "arguments": run_error_arguments(error),
             "allowed_values": run_error_allowed_values(error),
             "provider_code": run_info.get("returncode") if error_source == "provider" else None,