cdx-manager 0.14.0 → 0.15.0

package/README.md

@@ -1,20 +1,52 @@
 # CDX Manager
 
-[![License](https://img.shields.io/badge/license-MIT-4C8BF5)](LICENSE) ![Version](https://img.shields.io/badge/version-v0.14.0-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.15.0-4C8BF5) ![Python](https://img.shields.io/badge/python-3.9%2B-3776AB?logo=python&logoColor=white)
 
-**Run multiple Codex, Claude, Antigravity, and Ollama sessions from one terminal. Switch between accounts instantly.**
+**Stop guessing which AI account still has quota.** `cdx` tracks the rate-limit window of every Codex and Claude account you own, tells you which one is usable right now, and launches it with isolated auth — in one command.
 
-If you use AI coding tools at scale ; multiple accounts, multiple providers : you know the friction: re-authenticating, losing context, juggling environment variables. `cdx` removes all of that.
+If you pay for several AI coding subscriptions, you know the dance: you hit a 5-hour limit mid-task, guess which other account still has room, re-authenticate, and lose your context on the way. `cdx` turns that into `cdx next`.
 
-One command to launch any session. Zero auth juggling.
+![cdx status: remaining 5-hour and weekly quota for fifteen accounts, with the recommended one first](docs/assets/status.png)
 
-<img width="213" height="227" alt="image" src="https://github.com/user-attachments/assets/f15f449c-d23e-47fe-a455-17c7386f9be2" />
-<img width="645" height="129" alt="image" src="https://github.com/user-attachments/assets/34bcb395-f832-4da6-9247-3e5022e75e56" />
+---
+
+## Quick Start
+
+```bash
+npm install -g cdx-manager
+
+cdx add codex work      # register an isolated Codex profile named "work"
+cdx add claude perso    # and a Claude one
+cdx status              # every account's remaining quota, side by side
+cdx next                # which account should I use right now?
+```
+
+Supported providers: `codex`, `claude`, `antigravity`, `ollama`.
+
+`cdx next` answers the question you actually have, and prints the command to run:
+
+![cdx next: work1 selected at 100% quota, with the reason and the command to run](docs/assets/next.png)
+
+---
+
+## The Core Five
+
+Everything else is optional. These five cover the daily loop:
+
+| Command | What it gives you |
+|---|---|
+| `cdx add <provider> <name>` | An isolated account profile — its own auth, its own home |
+| `cdx <name>` | Launch that account, auth checked first |
+| `cdx status` | Remaining 5-hour and weekly quota for every account at once |
+| `cdx next` | The account you should use right now, and why |
+| `cdx run --prompt ... --json` | The same routing, headless, for scripts and agents |
 
 ---
 
 ## Table of Contents
 
+- [Quick Start](#quick-start)
+- [The Core Five](#the-core-five)
 - [What it does](#what-it-does)
 - [Technical Overview](#technical-overview)
 - [Getting Started](#getting-started)
@@ -32,24 +64,58 @@ One command to launch any session. Zero auth juggling.
 
 ## What it does
 
+### Quota-aware routing
+
+The reason `cdx` exists: knowing, across every account you own, which one you can actually use.
+
+- **Usage at a glance.** `cdx status` shows token usage, 5-hour window quota, weekly quota, last-updated timestamps, priority guidance, and the last launched session in one aligned table.
+- **Pick for me.** `cdx next` selects the best available assistant from your pinned priorities and the live quota picture, shows the reason, and prints the exact command to run.
+- **Next-ready notification.** `cdx ready` schedules a native system notification for the next assistant that comes back from cooldown, then returns immediately. `cdx notify` covers reset times and scheduled wake-ups.
+- **Passive status resolution.** Codex status is read from the local Codex app-server rate-limit API when available, with legacy transcript/history parsing kept as a fallback.
+- **Banked reset visibility.** Eligible Codex accounts show the number of manually redeemable bonus resets in `cdx status` and expose reset details in JSON output.
+
+### Isolated multi-account sessions
+
+![cdx: every registered session with its provider, state, pinned launch settings and age](docs/assets/list.png)
+
 - **Multiple providers, one tool.** Register as many Codex, Claude, Antigravity, or Ollama sessions as you need. Codex and Claude get isolated auth environments; Antigravity is launchable through `agy` with OS-keyring auth; Ollama runs local models through `ollama run`.
 - **Instant launch.** `cdx work` opens your "work" session. `cdx personal` opens another. No config files to edit mid-flow.
 - **Quick relaunch.** `cdx last` reopens the most recently launched assistant profile.
+- **Resume by identity, not by recency.** Each session records the provider's own conversation id — imposed at launch for Claude, read back from the rollout for Codex — so `cdx resume <name>` reopens *that* conversation regardless of your working directory or of which session ran last. `cdx can-resume --json` reports the strategy and where the id came from, so an automated caller can tell a named resume from a best-effort one.
 - **Auth guardrails.** `cdx` checks authentication before launching. If a session is not logged in, it tells you exactly what to run — no silent failures.
-- **Optional session labels.** `cdx label <name> <label>` adds a short human label; list and full status tables show a `LABEL` column only when at least one session has one.
-- **Usage at a glance.** `cdx status` shows token usage, 5-hour window quota, weekly quota, last-updated timestamps, priority guidance, and the last launched session in one aligned table.
-- **Next-ready notification.** `cdx ready` schedules a native system notification for the next assistant that comes back from cooldown, then returns immediately.
-- **Session control.** Disable a session without deleting it when an account is temporarily out of credits; disabled sessions remain visible and sort last.
 - **Persistent launch settings.** Pin per-session power, permission, and fast-mode preferences once; `cdx` reapplies them on every launch until you unset them.
+- **Spend ceiling and model fallback.** `cdx set <name> --budget 5` caps what a headless run may spend, and `--fallback-model sonnet,haiku` lets a run continue on the next model when the first is overloaded. Both are Claude Code flags that the provider accepts with `--print` only, so they apply to `cdx run` and not to interactive launches; `cdx configs` says so.
+- **Session control.** Disable a session without deleting it when an account is temporarily out of credits; disabled sessions remain visible and sort last.
+- **Optional session labels.** `cdx label <name> <label>` adds a short human label; list and full status tables show a `LABEL` column only when at least one session has one.
+- **Clean removal.** `cdx rmv` wipes a session and its entire auth directory. No orphaned files, no stale credentials.
+
+### Headless automation
+
+- **One task, one JSON result.** `cdx run` executes a prompt against a chosen or auto-selected session and returns a stable payload; `--detach` returns a `run_id` immediately.
+- **Survives a rate limit.** `cdx run --failover` notices that a run stopped because its account ran out, moves the task to the next account the ranking allows, and carries on — one `run_id` for the whole task, with every account it occupied listed in `cdx run-report`. A spent account is always confirmed against its own refreshed quota first, so a healthy account is never abandoned. From there two routes migrate a run: the provider said so in words cdx recognises, or — since that wording differs between an enterprise workspace out of credits, a personal plan hitting its 5-hour window, and Claude's own phrasing — simply that the account's quota is gone and the run failed. `cdx run-report` names which route applied. Exhausting every account reports `failover_exhausted`, which a caller can tell apart from the task itself failing.
+- **Native background delegation (opt-in).** With `CDX_EXPERIMENTAL_NATIVE_BG=1`, `cdx run --detach` hands the run to Claude Code's own background agents (`--bg`) instead of cdx's detached launcher. The run keeps its cdx `run_id`, closes out with its token usage and final answer read from the provider's own session transcript, and the parked session is stopped once its task is done. Off by default for one release while it settles; the in-house launcher is unchanged and is what every run takes otherwise. Codex keeps the in-house path while its `cloud`/`exec-server` surfaces are marked experimental.
+- **Observable runs.** `cdx run-status`, `cdx run-tail`, `cdx run-report`, and `cdx runs --since` follow a run while it happens and after it ends.
+- **Selection without launching.** `cdx select --provider ... --require-ready --json` answers "which session should this job use?" for orchestrators.
+- **Escape hatch for unmapped flags.** `cdx set <name> --extra-args "--add-dir ../shared"` passes provider arguments cdx does not model straight through, so a flag your provider shipped last week never forces you to abandon cdx. These arguments are explicitly unvalidated: cdx does not parse or verify them, `cdx schema --json` lists them under `unvalidated` rather than describing them, and `cdx doctor --check-provider-flags` ignores them. They are split into literal argv entries and never passed through a shell.
+- **Validated contract.** `cdx schema --json` publishes the enums, mutually-exclusive argument groups, and error codes programmatic callers should validate against.
+
+### Context handoff
+
+- **Shared handoff context.** Keep a per-workspace Markdown context, or build one from a source session transcript, and install it into another assistant session before switching providers or accounts.
+- **Session transcript capture.** Every launch is recorded to a local log file via `script`, giving you a full terminal transcript for each session.
+
+### Maintenance
+
 - **Launch history.** Inspect recent launches with provider, result, duration, working directory, launch settings, and transcript path.
+- **Aggregate usage.** `cdx stats` totals runs, token usage, and time spent per session over any period.
+
+![cdx stats: runs, input and output tokens, total time and last use per session](docs/assets/stats.png)
+
 - **Disk usage and cleanup.** `cdx disk` reports `CDX_HOME` usage, `cdx disk profiles --candidates` identifies reclaimable profile caches/logs with evidence, and `cdx clean profiles ...` applies explicit cleanup actions.
+- **Health and repair.** `cdx doctor` inspects dependencies, permissions, and orphan profiles; `cdx repair` plans or applies safe fixes.
+- **Portable bundles.** `cdx export` / `cdx import` move sessions between machines, with passphrase-encrypted auth data when you ask for it.
 - **Update prompts.** Periodic update checks surface `cdx update` directly in the `cdx`, `cdx status`, and launch output when a newer release is available. When `logics-manager` is installed, `cdx` can also suggest `logics-manager self-update`.
 - **Logics viewer shortcut.** `cdx view` opens the Logics browser/focus viewer through `logics-manager view` when the companion CLI is installed. All viewer flags are forwarded: `--lan`, `--lan-rw`, `--focus <ref>`, `--read`, `--port`, `--host`, `--refresh-interval`, `--tls`, `--tls-cert`, `--tls-key`, `--open`, `--no-open`. `cdx view --json` reports availability and update diagnostics without opening the viewer.
-- **Shared handoff context.** Keep a per-workspace Markdown context, or build one from a source session transcript, and install it into another assistant session before switching providers or accounts.
-- **Passive status resolution.** Codex status is read from the local Codex app-server rate-limit API when available, with legacy transcript/history parsing kept as a fallback.
-- **Banked reset visibility.** Eligible Codex accounts show the number of manually redeemable bonus resets in `cdx status` and expose reset details in JSON output.
-- **Session transcript capture.** Every launch is recorded to a local log file via `script`, giving you a full terminal transcript for each session.
-- **Clean removal.** `cdx rmv` wipes a session and its entire auth directory. No orphaned files, no stale credentials.
 
 ---
 
@@ -357,8 +423,8 @@ cdx history --summary --from 2026-05-01 --to 2026-05-28
 | `cdx config <name> [--json]` | Show persistent launch settings for a session |
 | `cdx configs [--json]` | Show persistent launch settings for all sessions in one table |
 | `cdx power\|perm\|fast\|model <name\|all\|provider:PROVIDER\|a,b> <value\|default> [--json]` | Shortcut commands for setting or clearing one launch setting |
-| `cdx set <name>\|--sessions all\|a,b\|--provider PROVIDER [--power minimal\|low\|medium\|high\|xhigh] [--permission review\|default\|auto\|full] [--fast on\|off] [--rtk on\|off] [--logics on\|off] [--model MODEL] [--priority 0..100] [--json]` | Persist launch settings for one or more sessions |
-| `cdx unset <name>\|--sessions all\|a,b\|--provider PROVIDER (--power\|--permission\|--fast\|--rtk\|--logics\|--model\|--priority\|--all) [--json]` | Remove persisted launch settings and fall back to provider defaults |
+| `cdx set <name>\|--sessions all\|a,b\|--provider PROVIDER [--power minimal\|low\|medium\|high\|xhigh] [--permission review\|default\|auto\|full] [--fast on\|off] [--rtk on\|off] [--logics on\|off] [--model MODEL] [--fallback-model MODEL[,MODEL...]] [--budget USD] [--extra-args 'ARGS'] [--priority 0..100] [--json]` | Persist launch settings for one or more sessions |
+| `cdx unset <name>\|--sessions all\|a,b\|--provider PROVIDER (--power\|--permission\|--fast\|--rtk\|--logics\|--model\|--fallback-model\|--budget\|--extra-args\|--priority\|--all) [--json]` | Remove persisted launch settings and fall back to provider defaults |
 | `cdx history [name] [--limit N] [--summary] [--since 7d\|today\|DATE] [--from DATE] [--to DATE] [--json]` | Show recent launch history or aggregate total launch time per assistant, optionally filtered by period |
 | `cdx last [--json]` | Launch the most recent existing session from launch history |
 | `cdx resume <name> [--json]` | Resume the provider-native conversation for a session using the named command form |
@@ -384,7 +450,7 @@ cdx history --summary --from 2026-05-01 --to 2026-05-28
 | `cdx notify --next-ready [--poll seconds] [--once] [--schedule] [--refresh] [--json]` | Wait until the recommended session is usable, or schedule the next known reset notification |
 | `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] [--reasoning-effort minimal\|low\|medium\|high\|xhigh] [--power minimal\|low\|medium\|high\|xhigh] [--permission MODE] [--timeout-seconds N] [--detach] [--refresh] --json` | Run one headless task and return a stable JSON result; `--detach` returns the `run_id` at launch without waiting, `--prompt-file -` reads the prompt from stdin |
+| `cdx run [session] --cwd PATH (--prompt-file PATH\|--prompt TEXT\|--prompt-file -) [--provider PROVIDER] [--model MODEL] [--reasoning-effort minimal\|low\|medium\|high\|xhigh] [--power minimal\|low\|medium\|high\|xhigh] [--permission MODE] [--timeout-seconds N] [--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, `--prompt-file -` reads the prompt from stdin |
 | `cdx run-report <run_id> --json` | Full report, transcript metadata, and final payload for a run |
 | `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 |

package/changelogs/CHANGELOGS_0_15_0.md

@@ -0,0 +1,139 @@
+# CDX Manager 0.15.0
+
+> Quota awareness stops being advice. A headless run that hits a rate limit now
+> continues on an account that still has quota, and `cdx resume` reopens the
+> conversation cdx named rather than whatever ran here last.
+
+## Read this first
+
+Two defaults change for existing sessions.
+
+- **`cdx resume <name>` changes meaning.** It used to run `codex resume --last`
+  or `claude --continue`, both of which mean "the most recent conversation in
+  this directory". It now names the provider's own conversation id, so it
+  reopens the conversation *that session* last had, regardless of your working
+  directory or of what ran since. Sessions with no recorded id keep the old
+  behaviour; `cdx can-resume --json` tells you which applies.
+- **Every Claude launch now carries `--session-id`.** cdx mints the id and
+  passes it, which is what makes the above possible.
+
+## Highlights
+
+- `cdx run --failover` continues a task on the next eligible account when the
+  one it started on runs out, keeping one `run_id` for the whole task.
+- `cdx set --budget` caps what a headless run may spend; `--fallback-model`
+  lets it continue on another model when the first is unavailable.
+- `cdx set --extra-args` passes provider flags cdx does not model straight
+  through, so a flag your provider shipped last week no longer forces you out
+  of cdx.
+- Resume and handoff are anchored on a provider-native conversation id instead
+  of on recency.
+- Opt-in delegation of `cdx run --detach` to Claude Code's own background
+  agents, behind `CDX_EXPERIMENTAL_NATIVE_BG=1`.
+
+## Changes
+
+### Failover across accounts
+
+`cdx run --failover` detects that a run stopped because its account is spent,
+re-ranks the remaining sessions through the same ranking `cdx next` uses,
+carries the task across, and continues. The whole task keeps one `run_id`;
+`cdx run-report` lists every session it occupied, in order, with the reason for
+each transition, and `cdx runs` shows it once.
+
+Migration requires the account's own refreshed rate-limit status to confirm it
+is spent, because the two ways of being wrong are not symmetric: missing a rate
+limit costs nothing new, while inventing one would move a healthy run off a
+working account and spend a second account's quota redoing it.
+
+Two routes trigger it. `provider_reported_exhaustion` when the provider says so
+in words cdx recognises, and `account_status_exhausted` when the quota is gone
+and the run failed, whatever the wording. The second exists because the wording
+is not one thing — an enterprise workspace out of credits, a personal plan
+hitting its 5-hour window, and Claude's own phrasing are different sentences,
+and only the first has been observed.
+
+Exhausting every eligible account reports `failover_exhausted`, and hitting the
+transition bound reports `failover_limit_reached`; both are distinct from the
+task itself failing. `--failover` and `--detach` are mutually exclusive:
+failover has to watch the run to react.
+
+### Spend ceiling and model fallback
+
+`cdx set <name> --budget 5` and `--fallback-model sonnet,haiku` persist like
+every other launch setting. Both are Claude Code flags the provider accepts
+only alongside `--print`, so they apply to `cdx run` and to nothing else;
+`cdx configs` says so rather than letting a launch fail. `--fallback-model`
+takes a comma-separated list, tried in order.
+
+### Resume by identity
+
+Sessions record the provider's own conversation id and where it came from.
+Claude accepts a caller-supplied id, so cdx mints it at launch — provenance
+`imposed`. Codex mints its own, so cdx reads it back from the rollout after a
+run — provenance `observed`, and legitimately absent until the session has run
+once. `cdx can-resume --json` reports the strategy, the id, and its provenance,
+so an automated caller can tell a named resume from a best-effort one.
+
+### Passthrough for unmapped provider flags
+
+`cdx set <name> --extra-args "--add-dir ../shared"` reaches the provider
+command line unmodified, after the arguments cdx maps itself, so a passthrough
+value overrides the setting it duplicates. These arguments are explicitly
+unvalidated: `cdx schema --json` lists them under `unvalidated` rather than
+describing them, and `cdx doctor --check-provider-flags` ignores them. They are
+split into literal argv entries and never passed through a shell.
+
+### Background delegation (opt-in)
+
+With `CDX_EXPERIMENTAL_NATIVE_BG=1`, `cdx run --detach` hands the run to Claude
+Code's background agents. The run keeps its cdx `run_id`, closes out with the
+token usage and final answer read from the provider's own session transcript,
+and the parked session is stopped once its task is done. Off by default for
+this release: it works, but it has been exercised far less than the in-house
+launcher every run takes today. Codex keeps the in-house path while its
+`cloud` and `exec-server` surfaces are marked experimental.
+
+### Onboarding and docs
+
+`cdx` with no sessions registered now points at `cdx add` instead of listing
+ten commands that all return nothing. The README leads with the quota routing
+rather than with session management, and its screenshots are generated from a
+synthetic home (`scripts/seed_demo_home.py`) so they carry no account names.
+
+### Fixes
+
+- A status merge adopted the candidate's timestamp even when it was older,
+  dating a record by its stalest contributor. Since `updated_at` drives the
+  freshness check, a just-resolved status read as expired and re-probed the
+  provider on every call.
+
+## Validation
+
+- `npm run lint`
+- `npm test` — 629 tests.
+- CI green on ubuntu-latest and windows-latest.
+- Also run on a physical Windows machine: 623 passed, 5 skipped. One failure,
+  `test_concurrent_starts_do_not_lose_records`, reproduces identically on the
+  `v0.14.0` tag on that machine and passes in CI — a pre-existing contention
+  flake in the registry lock, not a regression.
+- End-to-end across eleven live sessions and both providers: fourteen real
+  runs, usage extracted on every one, six Codex accounts each recording a
+  distinct conversation id and five Claude accounts recording theirs.
+- End-to-end failover on a genuinely exhausted account: `work6` migrated to
+  `work1` and the task succeeded, recorded as one run.
+- End-to-end resume by identity: a minted id accepted as `--session-id`, then
+  `--resume` on that id recalling the previous turn's answer.
+- `--extra-args` and the budget/fallback settings exercised against real
+  provider CLIs, not only in tests.
+- `logics-manager lint --require-status`
+- `logics-manager audit --group-by-doc` — 0 blocking, 0 warnings.
+
+## Known gaps
+
+- The rate-limit wording of a personal-plan Codex account and of Claude has not
+  been observed; only an enterprise workspace out of credits has. The
+  `account_status_exhausted` route covers the unobserved cases, so this costs
+  the precise reason rather than the failover itself.
+- Background delegation has been exercised on one account with one prompt
+  shape, which is why it is opt-in.

package/checksums/release-archives.json

@@ -160,6 +160,18 @@
     "v0.12.2": {
       "github_tarball_sha256": "5214f9f85f6bdc2c53bded938c91e28411de3c573bbcff81ebecb20dea6d99c2",
       "github_zip_sha256": "8f447cdea9e921f7428c1c72db5a19f40f447a877bb2bc8dc1c8bd5e34daf070"
+    },
+    "v0.12.3": {
+      "github_tarball_sha256": "b41cf8a99c36d3f03a3556db604316dcfdf14e2eb9090c86f25190b8a0db866a",
+      "github_zip_sha256": "6a8e384a88e736607dbc0b6e9953fb61192e77ded259fac2de35b03ad2fa71bd"
+    },
+    "v0.12.4": {
+      "github_tarball_sha256": "877e54c9f435acb41947c43c8618c84d88e0dc0c7cb77c5dd5dc56e13ee80b7f",
+      "github_zip_sha256": "7db7f28ab8b295446ba0a38e6e3cbbcc8855dd7333ebc9877917d14b4caaf903"
+    },
+    "v0.14.0": {
+      "github_tarball_sha256": "5da107556442d3566a7b0787708ae700e38afdf99e74209fffd2484ce3a33d94",
+      "github_zip_sha256": "bd4e070582bfc641e6176a8b8be8d7afd1ce9d76fc59c1dbeb238bae548bc699"
     }
   }
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "cdx-manager",
-  "version": "0.14.0",
+  "version": "0.15.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.14.0"
+version = "0.15.0"
 description = "Terminal session manager for Codex and Claude accounts."
 readme = "README.md"
 requires-python = ">=3.9"

package/src/cli_args.py

@@ -8,6 +8,7 @@ imported back there and used by the handlers.
 from datetime import datetime, timedelta
 
 from .config import (
+    MAX_LAUNCH_BUDGET_USD,
     PERMISSION_ALIASES,
     PERMISSION_INPUT_VALUES,
     PERMISSION_VALUES,
@@ -30,8 +31,8 @@ CONTEXT_USAGE = "Usage: cdx context show|path|init|edit|clear|set|append [text..
 MEMORY_USAGE = "Usage: cdx memory [--global|--project NAME_OR_PATH] [show|view|path|init|edit|clear|set|append|list] [text...] [--json]"
 HANDOFF_USAGE = "Usage: cdx handoff <name> [--json] | cdx handoff <source> <target> [--json]"
 LABEL_USAGE = "Usage: cdx label <name> <label> [--json] | cdx label <name> --clear [--json]"
-SET_USAGE = "Usage: cdx set <name>|--sessions all|a,b|--provider PROVIDER [--power minimal|low|medium|high|xhigh] [--permission review|default|auto|full] [--fast on|off] [--rtk on|off] [--logics on|off] [--model MODEL] [--priority 0..100] [--json]"
-UNSET_USAGE = "Usage: cdx unset <name>|--sessions all|a,b|--provider PROVIDER (--power|--reasoning-effort|--permission|--fast|--rtk|--logics|--model|--priority|--all) [--json]"
+SET_USAGE = "Usage: cdx set <name>|--sessions all|a,b|--provider PROVIDER [--power minimal|low|medium|high|xhigh] [--permission review|default|auto|full] [--fast on|off] [--rtk on|off] [--logics on|off] [--model MODEL] [--fallback-model MODEL[,MODEL...]] [--budget USD] [--extra-args 'ARGS'] [--priority 0..100] [--json]"
+UNSET_USAGE = "Usage: cdx unset <name>|--sessions all|a,b|--provider PROVIDER (--power|--reasoning-effort|--permission|--fast|--rtk|--logics|--model|--fallback-model|--budget|--extra-args|--priority|--all) [--json]"
 SETTING_ALIAS_USAGE = "Usage: cdx power|perm|fast|model <name|all|provider:PROVIDER|a,b> <value|default> [--json]"
 CONFIG_USAGE = "Usage: cdx config <name> [--json]"
 CONFIGS_USAGE = "Usage: cdx configs [--json]"
@@ -42,12 +43,13 @@ RESUME_USAGE = "Usage: cdx resume <name> [--json]"
 CAN_RESUME_USAGE = "Usage: cdx can-resume <name> [--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 PATH (--prompt-file PATH|--prompt TEXT|--prompt-file -) [--provider PROVIDER] [--model MODEL] [--kind assistant|code-review] [--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] [--timeout-seconds N] [--detach] [--refresh] --json"
+RUN_USAGE = "Usage: cdx run [session] --cwd PATH (--prompt-file PATH|--prompt TEXT|--prompt-file -) [--provider PROVIDER] [--model MODEL] [--kind assistant|code-review] [--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] [--timeout-seconds N] [--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."
 RUN_CWD_REQUIRED = "cdx run: --cwd PATH is required."
 RUN_PROMPT_SOURCE_REQUIRED = "cdx run: specify exactly one prompt source: --prompt TEXT or --prompt-file PATH."
+RUN_DETACH_FAILOVER_CONFLICT = "cdx run: --failover needs to watch the run, which --detach gives up."
 RUN_KIND_VALUES = ("assistant", "code-review")
 # Aliases of the shared definitions in config, kept only so the existing
 # RUN_* spellings in this module keep reading naturally. They are references,
@@ -228,6 +230,17 @@ def _parse_priority_value(value):
     return priority
 
 
+def _parse_budget_value(value):
+    try:
+        budget = float(value)
+    except (TypeError, ValueError) as error:
+        raise CdxError(SET_USAGE) from error
+    # NaN compares false against every bound, so reject it before the range check.
+    if budget != budget or budget <= 0 or budget > MAX_LAUNCH_BUDGET_USD:
+        raise CdxError(SET_USAGE)
+    return budget
+
+
 def _parse_set_args(args):
     parsed = _parse_flag_args(args, {
         "--power": {"key": "power", "type": "str", "default": None},
@@ -236,6 +249,9 @@ def _parse_set_args(args):
         "--rtk": {"key": "rtk", "type": "str", "default": None, "transform": _parse_fast_value},
         "--logics": {"key": "logics", "type": "str", "default": None, "transform": _parse_fast_value},
         "--model": {"key": "model", "type": "str", "default": None},
+        "--fallback-model": {"key": "fallback_model", "type": "str", "default": None},
+        "--budget": {"key": "budget", "type": "str", "default": None, "transform": _parse_budget_value},
+        "--extra-args": {"key": "extra_args", "type": "str", "default": None},
         "--priority": {"key": "priority", "type": "str", "default": None, "transform": _parse_priority_value},
         "--sessions": {"key": "sessions", "type": "str", "default": None, "transform": _parse_set_unset_sessions},
         "--provider": {"key": "provider", "type": "str", "default": None, "transform": lambda value: _parse_provider_filter(value, SET_USAGE)},
@@ -253,7 +269,7 @@ def _parse_set_args(args):
         raise CdxError(SET_USAGE)
     settings = {
         key: parsed[key]
-        for key in ("power", "permission", "fast", "rtk", "logics", "model", "priority")
+        for key in ("power", "permission", "fast", "rtk", "logics", "model", "fallback_model", "budget", "extra_args", "priority")
         if parsed[key] is not None
     }
     if not settings:
@@ -276,6 +292,9 @@ def _parse_unset_args(args):
         "--rtk": {"key": "rtk", "type": "bool", "default": False},
         "--logics": {"key": "logics", "type": "bool", "default": False},
         "--model": {"key": "model", "type": "bool", "default": False},
+        "--fallback-model": {"key": "fallback_model", "type": "bool", "default": False},
+        "--budget": {"key": "budget", "type": "bool", "default": False},
+        "--extra-args": {"key": "extra_args", "type": "bool", "default": False},
         "--priority": {"key": "priority", "type": "bool", "default": False},
         "--all": {"key": "all", "type": "bool", "default": False},
         "--sessions": {"key": "sessions", "type": "str", "default": None, "transform": _parse_set_unset_sessions},
@@ -292,9 +311,11 @@ def _parse_unset_args(args):
         raise CdxError(UNSET_USAGE)
     if not parsed["names"] and not parsed["sessions"] and not parsed["provider"]:
         raise CdxError(UNSET_USAGE)
-    keys = ["power", "reasoning_effort", "permission", "fast", "rtk", "logics", "model", "priority"] if parsed["all"] else [
-        key for key in ("power", "reasoning_effort", "permission", "fast", "rtk", "logics", "model", "priority") if parsed[key]
-    ]
+    _UNSET_KEYS = (
+        "power", "reasoning_effort", "permission", "fast", "rtk", "logics",
+        "model", "fallback_model", "budget", "extra_args", "priority",
+    )
+    keys = list(_UNSET_KEYS) if parsed["all"] else [key for key in _UNSET_KEYS if parsed[key]]
     if not keys:
         raise CdxError(UNSET_USAGE)
     return {
@@ -426,6 +447,16 @@ def cdx_schema():
             "kind": {"accepted": list(RUN_KIND_VALUES)},
             "provider": {"accepted": list(PROVIDERS)},
         },
+        # Passthrough arguments are deliberately absent from this contract.
+        # `cdx set --extra-args` reaches the provider unchanged and cdx never
+        # validates it, so publishing it here would claim a guarantee that does
+        # not exist. A caller must treat it as opaque.
+        "unvalidated": {
+            "extra_args": {
+                "reason": "Passed to the provider CLI unchanged; cdx neither parses nor verifies these arguments.",
+                "not_checked_by": ["cdx schema", "cdx doctor --check-provider-flags"],
+            },
+        },
         "mutually_exclusive": [
             {
                 "command": "run",
@@ -437,6 +468,11 @@ def cdx_schema():
                 "arguments": ["--prompt-file", "--prompt"],
                 "reason": "Exactly one prompt source.",
             },
+            {
+                "command": "run",
+                "arguments": ["--detach", "--failover"],
+                "reason": "Failover has to watch the run to react to a rate limit; --detach stops watching.",
+            },
         ],
         # Not mutually exclusive: both may be given, and cdx accepts them when
         # they agree. A caller generating validation from `mutually_exclusive`
@@ -554,6 +590,7 @@ def _parse_run_args(args):
         "--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},
         "--detach": {"key": "detach", "type": "bool", "default": False},
+        "--failover": {"key": "failover", "type": "bool", "default": False},
         "--refresh": {"key": "refresh", "type": "bool", "default": False},
         "--json": {"key": "json", "type": "bool", "default": False},
     }, RUN_USAGE, positionals_key="names", max_positionals=1)
@@ -576,6 +613,12 @@ def _parse_run_args(args):
             code=ARG_CODE_MUTUALLY_EXCLUSIVE,
             arguments=["--prompt-file", "--prompt"],
         )
+    if parsed["detach"] and parsed["failover"]:
+        raise CdxArgumentError(
+            RUN_DETACH_FAILOVER_CONFLICT,
+            code=ARG_CODE_MUTUALLY_EXCLUSIVE,
+            arguments=["--detach", "--failover"],
+        )
     if not parsed["prompt_file"] and not parsed["prompt"]:
         raise CdxArgumentError(
             RUN_PROMPT_SOURCE_REQUIRED,
@@ -602,6 +645,7 @@ def _parse_run_args(args):
         "permission": parsed["permission"],
         "timeout_seconds": parsed["timeout_seconds"],
         "detach": parsed["detach"],
+        "failover": parsed["failover"],
         "refresh": parsed["refresh"],
         "reasoning_effort": effort.get("reasoning_effort"),
         "power": effort.get("power"),

package/src/cli_helpers.py

@@ -487,6 +487,9 @@ def _format_launch_config(session, use_color=False):
         ("rtk", "RTK"),
         ("logics", "Logics"),
         ("model", "Model"),
+        ("fallback_model", "Fallback"),
+        ("budget", "Budget"),
+        ("extra_args", "Extra args"),
         ("priority", "Priority"),
     ]:
         rows.append([
@@ -520,6 +523,10 @@ def _format_launch_setting_value(launch, key, use_color=False):
     value = launch.get(key)
     if value is None or value == "":
         return _dim("default", use_color)
+    if key == "budget":
+        from .provider_runtime import _format_budget_arg
+
+        return _style(_format_budget_arg(value), "33", use_color)
     if key == "priority":
         return _style(str(value), "33", use_color)
     if key == "power":
@@ -535,6 +542,12 @@ def _resume_capability_for_session(session, ctx):
         "provider": session["provider"],
         "resumable": bool(capability.get("resumable")),
         "strategy": capability.get("strategy"),
+        # A caller deciding whether to trust a resume needs to tell a named
+        # conversation from "whatever ran here last", and where that name came
+        # from: Claude's is imposed at launch, Codex's is observed afterwards
+        # and is legitimately absent until the session has run once.
+        "identity": capability.get("identity"),
+        "provenance": capability.get("provenance"),
         "reason": capability.get("reason"),
         "command_preview": capability.get("command_preview") or [],
     }

package/src/cli_render.py

@@ -120,8 +120,25 @@ def format_error(error, env=None, stderr=None):
     return _style(str(error), "31", _should_use_color(env or os.environ, stderr or sys.stderr))
 
 
+def _format_onboarding(use_color=False):
+    return "\n".join([
+        _style("No sessions yet.", "1", use_color),
+        "",
+        "A session is an isolated account profile for a provider CLI.",
+        "Register your first one, then launch it by name:",
+        "",
+        f"  {_style('cdx add codex work', '36', use_color)}     {_dim('register a Codex session named work', use_color)}",
+        f"  {_style('cdx work', '36', use_color)}               {_dim('log in if needed, then launch it', use_color)}",
+        "",
+        f"{_dim('Providers: codex, claude, antigravity, ollama (ollama needs --model).', use_color)}",
+        f"{_dim('Run cdx help for the full command list.', use_color)}",
+    ])
+
+
 def _format_sessions(service, use_color=False):
     rows = service["format_list_rows"]()
+    if not rows:
+        return _format_onboarding(use_color=use_color)
     has_provider = any(r.get("provider") for r in rows)
     has_label = any(r.get("label") for r in rows)
     has_launch = any(r.get("launch") for r in rows)