cdx-manager 0.12.4 → 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.12.4-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 |
@@ -374,7 +440,7 @@ cdx history --summary --from 2026-05-01 --to 2026-05-28
 | `cdx reset <name> [--yes] [--json]` | Explicitly consume one available banked Codex rate-limit reset; confirmation is required unless `--yes` is supplied |
 | `cdx export <file> [--include-auth] [--sessions a,b] [--passphrase-env VAR\|--passphrase-stdin] [--force] [--json]` | Export sessions to a portable bundle; `--include-auth` encrypts auth data with a passphrase |
 | `cdx import <file> [--sessions a,b] [--passphrase-env VAR\|--passphrase-stdin] [--force\|--merge] [--allow-authless-force] [--json]` | Import sessions from a bundle into the current `CDX_HOME` |
-| `cdx doctor [--severity OK|WARN|FAIL[,OK|WARN|FAIL...]] [--json]` | Inspect CLI dependencies, provider CLI versions/capability hints, CDX_HOME permissions, missing state, orphan profiles, and pending quarantines; optionally filter issue severities |
+| `cdx doctor [--severity OK|WARN|FAIL[,OK|WARN|FAIL...]] [--check-provider-flags] [--json]` | Inspect CLI dependencies, provider CLI versions/capability hints, CDX_HOME permissions, missing state, orphan profiles, and pending quarantines; optionally filter issue severities. `--check-provider-flags` additionally verifies that the CLI flags cdx maps for each permission are actually accepted by each provider's installed CLI |
 | `cdx repair [--dry-run] [--force] [--json]` | Plan or apply safe repairs for missing state files, quarantines, and orphan profiles |
 | `cdx view [--json] [--lan] [--lan-rw] [--focus <ref>] [--read] [--port <port>] [--host <host>] [--refresh-interval <s>] [--tls] [--tls-cert <path>] [--tls-key <path>] [--open] [--no-open]` | Open the Logics browser/focus viewer by delegating to `logics-manager view`; all viewer flags are forwarded; JSON mode reports diagnostics without launching it |
 | `cdx update [--check] [--yes] [--json] [--version TAG]` | Update cdx-manager using the installer that matches how it was installed |
@@ -384,7 +450,12 @@ 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) [--provider PROVIDER] [--model MODEL] [--reasoning-effort minimal\|low\|medium\|high\|xhigh] [--power minimal\|low\|medium\|high\|xhigh] [--permission MODE] [--timeout-seconds N] --json` | Run one headless task and return a stable JSON result |
+| `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 |
+| `cdx runs [--limit N] [--since 7d\|today\|DATE] --json` | List recent runs; `--since` returns every run completed after the cursor and ignores `--limit` |
+| `cdx schema --json` | Publish the enums, mutually-exclusive argument groups, and error codes programmatic callers should validate against |
 | `cdx stats [name] [--since 7d\|today\|DATE] [--from DATE] [--to DATE] [--json]` | Aggregate launch counts, duration, and known headless token usage by session |
 | `cdx status [--json] [--refresh\|--cached] [--timeout SECONDS]` | Show token usage table for all sessions; `--cached` skips live provider probes and returns only stored status |
 | `cdx status --small [--refresh\|--cached] [--timeout SECONDS]` / `cdx status -s [--refresh\|--cached] [--timeout SECONDS]` | Show compact token usage table without provider, blocking quota, credits, and updated columns |
@@ -506,6 +577,130 @@ cdx stats work
 cdx select --provider codex --min-reasoning-effort low --require-ready --json
 ```
 
+### How cdx picks a session
+
+`cdx select`, `cdx run --provider`, `cdx next`, the `cdx status` recommendation, and `cdx ready` all use one ranking. They used to use two that disagreed, so the answer depended on which command you asked.
+
+**Candidate filters** exclude sessions before any ordering happens: disabled sessions, logged-out sessions (they cannot serve work), sessions of another provider when one is requested, sessions below a requested `--min-reasoning-effort`, and — when readiness is required — sessions with no availability left.
+
+**Ordering** compares the remaining candidates factor by factor:
+
+1. **Usability** — usable now, then blocked with a known upcoming reset, then reset known, then nothing known.
+2. **Priority** — the `--priority` you set with `cdx set <name> --priority 0..100`, highest first.
+3. Then, for a session you can use now: **credits** (sessions *without* credits first, so included quota is spent before paid credits), **availability**, **reset time**. For a session you cannot use now the order is **reset time** first, then credits and availability — when you cannot use it, what matters is when it comes back.
+4. **Reasoning effort** — the lowest configured effort that still clears any requested floor, leaving stronger sessions free for work that needs them.
+5. **Session name**, so the order is deterministic.
+
+`--priority` ranks sessions *within* a usability class, never across one. A high-priority session with no quota left does not outrank a usable one: priority expresses which usable session to prefer, not a way to route work somewhere it will fail.
+
+`cdx select --json` reports `selection_policy` (built from the ranking itself, so it cannot describe an order the code does not apply) and `deciding_factor`/`reason`, naming the factor that actually separated the winner from the runner-up for that call — or reporting that it was the only candidate. Do not treat `selection_policy` as a stable identifier; it changes when the ranking changes, which is the point.
+
+`cdx run --provider` selects from cached status by default. Pass `--refresh` to fetch status first. When a session is auto-selected without any recorded availability, the run payload carries a `session_selected_without_status` warning — that is different from a session known to be low, and on a freshly imported or long-idle set of sessions it is the ordinary case.
+
+### Verifying provider flag mappings
+
+cdx translates each `--permission` value into concrete provider CLI flags. Those mappings are declarations about someone else's CLI, and a provider can drop or rename a flag without cdx noticing — which is exactly what happened with an `--experimental-yolo` flag mapped for ollama that the ollama CLI never had.
+
+`cdx doctor --check-provider-flags` verifies them against the installed provider CLIs:
+
+```bash
+cdx doctor --check-provider-flags --json
+```
+
+For each configured provider it reports, per permission, whether every mapped flag is accepted. A rejected flag is a `FAIL` naming the provider, the permission, and the flag. A provider whose CLI is not installed, or whose help cannot be read, is a `WARN` — never an `OK`: "could not verify" is precisely the state a stale mapping hides in. A provider that maps no flags at all, such as ollama, reports `OK` with an empty mapping, so having nothing to check is distinguishable from having failed to check.
+
+It is opt-in because it costs one provider CLI invocation per configured provider. When it is not requested, the default `cdx doctor` report says so with a `provider_permission_flags_unchecked` warning rather than omitting it, so a green report never implies the mappings were verified.
+
+### Programmatic Callers
+
+`cdx run` blocks until the provider finishes, which suits a supervisor that can wait. Agents, MCP servers, and watchdogs usually cannot, so the surface below exists specifically for them: launch without waiting, watch progress, react to failures by code, and discover valid values instead of hard-coding them.
+
+**Launch without waiting.** `--detach` returns as soon as the run is registered, with the `run_id` already assigned:
+
+```bash
+cdx run work --cwd /path/to/repo --prompt-file task.md --detach --json
+```
+
+The payload carries `detached: true`, `run_id`, `pid`, and the artifact paths — but no `exit_code`, `duration_seconds`, or `usage`, since the run has not finished. The detached process is put in its own session, so it survives the launcher exiting, including when cdx was invoked over an SSH command that returns immediately. It transitions its own registry entry to a terminal status, so `cdx runs` and `cdx run-status` stay accurate with nobody supervising.
+
+Authentication is still resolved before the launch returns, so a login problem surfaces synchronously rather than silently in the background.
+
+**Watch a run in progress.** `cdx run-status` reports only running/succeeded/failed; `run-tail` shows what the run is actually doing:
+
+```bash
+cdx run-tail <run_id> --lines 50 --json
+```
+
+It returns the last lines of the run's own `stdout_path` plus its current status, whether the run is still going or already finished. Lines are raw provider output, not summarized. Undecodable bytes come back with replacement characters rather than failing the call.
+
+**Pipe an untrusted prompt.** `--prompt-file -` reads the prompt from standard input, so arbitrary text never has to reach a command line or a temporary file the caller must clean up:
+
+```bash
+echo "$UNTRUSTED_PROMPT" | cdx run work --cwd /path/to/repo --prompt-file - --json
+```
+
+It fails immediately if standard input is a terminal, rather than blocking at a silent prompt.
+
+**Poll for completions with a cursor.** `cdx runs --since` returns every run that completed after the cursor, using the same cursor forms as `cdx history --since`:
+
+```bash
+cdx runs --since 15m --json
+cdx runs --since 2026-08-07T09:00:00Z --json
+```
+
+A cursor is bounded by time, not by row count: `--limit` is ignored when `--since` is given (and says so in `warnings`). That is deliberate — capping a cursor query by row count would silently drop completions a caller had not yet seen, which is exactly the miss the cursor removes. Runs still in flight are not returned; they appear once they complete. Callers do not need to keep their own set of already-reported run ids.
+
+**React to failures by code, not by message.** Argument failures report a specific `error.code` and name the offending arguments as data:
+
+| `error.code` | Raised when |
+| --- | --- |
+| `missing_required_argument` | A required argument is absent |
+| `mutually_exclusive_arguments` | Two arguments that cannot be combined were both given |
+| `invalid_argument_value` | A constrained option got a value outside its accepted set |
+| `argument_value_out_of_range` | A numeric argument fell outside its accepted range |
+| `unknown_argument` | An unrecognized flag |
+
+```json
+{
+  "ok": false,
+  "error": {
+    "code": "mutually_exclusive_arguments",
+    "message": "cdx run: cannot specify both a session name and --provider.",
+    "arguments": ["session", "--provider"],
+    "allowed_values": null
+  }
+}
+```
+
+Never branch on `error.message`; it is written for a human reading a terminal and may be reworded.
+
+**Discover valid values.** `cdx schema --json` publishes the enums and argument constraints the parser itself validates against:
+
+```bash
+cdx schema --json
+```
+
+It returns accepted values for `permission` (with its aliases and canonical forms), `reasoning_effort`/`power`, `kind`, and `provider`, plus the declared mutually-exclusive argument groups and the error codes above. Validate against this rather than copying the lists into your own code — a hand-maintained copy drifts, and cdx will not tell you when it does.
+
+**Surface run warnings.** The run payload's `warnings` list reports degradations a zero exit code would otherwise hide, on the successful path as much as the failing one:
+
+```json
+{
+  "ok": true,
+  "exit_code": 0,
+  "warnings": [
+    {
+      "code": "network_disabled_by_permission",
+      "message": "codex runs at permission 'review' inside a sandbox with no network access, ...",
+      "provider": "codex",
+      "permission": "review"
+    }
+  ]
+}
+```
+
+Codex ties network access to its sandbox, so any permission below `full` leaves the run unable to resolve DNS — `gh`, `curl`, and package installs fail inside an otherwise successful run. Show these warnings to whoever reads your output rather than discarding them; a run that succeeds while quietly doing less is the case they exist for.
+
 ---
 
 ## Backup And Restore

package/changelogs/CHANGELOGS_0_14_0.md

@@ -0,0 +1,146 @@
+# CDX Manager 0.14.0
+
+> 0.13.0 was prepared but never published. Everything it contained ships here,
+> so this release covers two versions' worth of work: the programmatic CLI
+> surface for non-interactive callers, and the unification of session selection
+> and accepted values.
+
+## Highlights
+
+- `cdx run --detach` launches a run without waiting and returns its `run_id` immediately; `cdx run-tail` shows a run's live output.
+- `cdx schema --json` publishes the enums, constraints, and error codes callers should validate against, instead of forcing them to copy lists that drift.
+- Every command that picks a session now uses one ranking, and `--priority` finally counts in all of them.
+- `cdx set --permission workspace-write` works, matching what `cdx run --permission` always accepted.
+- New `cdx doctor --check-provider-flags` verifies that the CLI flags cdx maps for each permission actually exist in the provider CLIs.
+
+## Changes
+
+### Detached runs
+
+`cdx run --detach --json` registers the run, starts the provider detached from the invoking process, and returns straight away with `detached: true`, the assigned `run_id`, `pid`, and the artifact paths. The child is placed in its own session so it outlives the launcher, including when cdx was invoked over an SSH command that returns immediately, and it transitions its own registry entry to a terminal status so `cdx runs` and `cdx run-status` stay accurate with nobody supervising. Authentication is still resolved before the launch returns, so a login problem surfaces synchronously rather than in the background.
+
+Callers no longer have to poll `cdx runs` and guess which row belongs to the run they just started.
+
+### Live run output
+
+`cdx run-tail <run_id> [--lines N] --json` returns the last lines of a run's recorded `stdout_path` plus its current status, while the run is still going or after it finished. Undecodable provider bytes are returned with replacement characters rather than failing the call. A run with no recorded output path reports `run_output_unavailable`, distinct from an unreadable one.
+
+### Specific argument error codes
+
+Argument and usage failures previously collapsed into `invalid_request` carrying the full human usage line, so a missing `--cwd` was indistinguishable from passing a session name and `--provider` together. They now report `missing_required_argument`, `mutually_exclusive_arguments`, `invalid_argument_value`, `argument_value_out_of_range`, or `unknown_argument`, and the error object gained `arguments` and `allowed_values` fields naming the offending arguments as data. The human-readable message and the exit codes are unchanged.
+
+`invalid_reasoning_effort` is kept for an unsupported `--reasoning-effort`/`--power` value; supplying two conflicting values now reports `mutually_exclusive_arguments`, since the two flags are aliases of one setting.
+
+### Schema discovery
+
+`cdx schema --json` publishes the accepted values for `permission` (with aliases and canonical forms), `reasoning_effort`/`power`, `kind`, and `provider`, the declared mutually-exclusive argument groups, and the argument error codes. Values are read from the same definitions the parser validates against, and a test fails if the two disagree, so downstream callers can stop maintaining copies that drift.
+
+### Prompts on standard input
+
+`cdx run --prompt-file -` reads the prompt from standard input, so a caller relaying arbitrary text no longer has to stage and clean up a temporary file or place the text on a command line. It fails immediately with `invalid_argument_value` if standard input is a terminal.
+
+### Completion cursor for runs
+
+`cdx runs --since <cursor> --json` returns every run that completed after the cursor, accepting the same cursor forms as `cdx history --since`. The cursor bounds the result by time rather than row count: `--limit` is ignored when `--since` is given, and the payload says so in `warnings`. Capping a cursor query by row count would silently drop completions a polling caller had not yet seen. Runs still in flight are excluded until they complete.
+
+### Run warnings
+
+The run payload's `warnings` list was declared in the contract but hardcoded empty. It is now populated, on the successful path as much as the failing one. The first warning, `network_disabled_by_permission`, fires when a Codex-backed run uses a permission below `full`: Codex ties network access to its sandbox, so the run cannot resolve DNS and network-dependent tooling fails inside a run that still exits zero. The condition is read from the same permission-to-flag mapping the launch spec uses, so adding a permission cannot leave it behind.
+
+### One session selection rule
+
+`cdx select`, `cdx run --provider`, `cdx next`, the `cdx status` recommendation, and `cdx ready` used two independent rankings that disagreed. Each knew something the other did not: the headless one filtered by provider and honored `--priority`, the recommendation one understood credits and reset scheduling. Which session you got depended on which command you asked.
+
+They are now one function in `src/session_ranking.py`, parameterized by what each caller needs. Candidate filters (disabled, logged out, provider, effort floor, readiness) are kept separate from ordering, because describing a filter as a sort stage is part of what made the old published policy wrong.
+
+The merged ordering is: usability class, then `--priority`, then — for a usable session — credits, availability and reset; for a session that is not usable now, reset first, since when it comes back is what matters. Reasoning effort and session name break the remaining ties.
+
+### The priority setting counts everywhere
+
+`cdx set <name> --priority 90` previously affected only `cdx select` and `cdx run --provider`. Status rows now carry the configured priority and effort, so `cdx next`, `cdx status`, and `cdx ready` honor it too.
+
+Priority ranks sessions *within* a usability class, never across one: a high-priority session with no quota left does not outrank a usable one. Priority says which usable session to prefer, not where to send work that will fail there.
+
+The `cdx status` recommendation line is now labelled `Recommended:` rather than `Priority:`. The old label named the whole recommendation after one of its inputs, so tuning `--priority` and seeing no change read as the setting being broken when availability or resets had decided instead.
+
+### Truthful selection reporting
+
+`cdx select --json` built its `selection_policy` from a hardcoded string that omitted the reasoning-effort tie-break and described the readiness filter as a sort stage, and a `reason` that claimed availability decided even when priority or the alphabetical fallback did.
+
+Both are now derived. `selection_policy` is built from the ranking itself and reports factors and filters separately; `deciding_factor` and `reason` name the factor that actually separated the winner from the runner-up for that call, or report that it was the only candidate. Do not treat `selection_policy` as a stable identifier — it changes when the ranking does, which is the point.
+
+### Selecting on fresh or missing status
+
+`cdx run --provider` now accepts `--refresh` to fetch status before auto-selecting. Cached status remains the default, so ordinary runs do not each pay for a provider probe.
+
+When auto-selection picks a session with no recorded availability, the run payload carries a `session_selected_without_status` warning. That is distinct from a session known to be low: on a freshly imported or long-idle set of sessions, choosing with no data at all is the ordinary case, and it was previously invisible.
+
+### One definition of the values cdx accepts
+
+The reasoning-effort enum was defined in four places (two of them identical, one line apart in the same module) and the permission enum in two, with `cdx set` validating against one pair and `cdx run` against another. `config.py` now owns both, and every validator, normalizer, and `cdx schema --json` derives from them. One test asserts identity rather than equality; another fails if any module restates one of these sets.
+
+### Permission aliases work in cdx set
+
+`cdx run --permission workspace-write` was accepted and normalized to `default`, while `cdx set <name> --permission workspace-write` failed with `Unsupported permission`. The same applied to `read-only` and `danger-full-access`, which are the provider-native spellings a user is most likely to have in hand, and `cdx schema --json` published the aliases without saying they applied to one command only.
+
+`cdx set` and the `perm` alias command now accept them, storing the canonical value so nothing downstream has to learn aliases exist. They were added to `set` rather than removed from `run`, since removing them would break callers passing provider-native spellings today.
+
+### Verifying provider flag mappings
+
+cdx maps each permission to concrete provider CLI flags, and nothing verified those mappings. GitHub issue #8 was exactly that: an `--experimental-yolo` flag mapped for ollama that the ollama CLI never had, undetected until a user hit it.
+
+`cdx doctor --check-provider-flags` checks each configured provider's installed CLI for the flags cdx maps. A rejected flag is a `FAIL` naming the provider, the permission, and the flag. An uninstalled CLI or unreadable help is a `WARN`, never an `OK` — "could not verify" is the state that bug lived in. A provider that maps nothing, such as ollama, reports `OK` with an empty mapping, so having nothing to check is distinguishable from having failed to check.
+
+It is opt-in because it costs a provider CLI invocation per provider, and the default report carries a `provider_permission_flags_unchecked` warning rather than omitting it, so a green doctor never implies the mappings were verified.
+
+Antigravity and ollama permission mappings also moved out of inline branches into `LAUNCH_PERMISSION_ARGS`, so every provider's mapping is declared in one table the check can read. Ollama's entry is deliberately empty.
+
+## Internal structure
+
+No behavior change, listed because the source layout is different if you have a patch in flight.
+
+`cli_commands.py` (3313 lines) became nine per-domain modules under `src/commands/`, and `session_service.py` (1690 lines) became `session_service`, `session_helpers`, `session_status`, and `session_backup`. `create_session_service` went from a 1153-line factory holding 46 closures to 56 lines of assembly, with dependencies passed explicitly rather than captured.
+
+Both original modules remain the import location for everything they exposed, so no caller changed. The split followed a coupling measurement in each case, and stopped where the measurement stopped: the session service's runtime and auth groups have no helpers of their own, so they were left in place rather than turned into files that would only re-import from elsewhere. That reasoning is recorded in `session_service`'s docstring, with a test that fails if someone finishes the job by instinct.
+
+## Behavior changes
+
+- **`--priority` now outranks availability.** It previously sat below availability in the headless sort, so it only broke exact ties and was effectively inert. A session with lower availability but higher priority now wins within the same usability class. This is the change that makes the setting mean anything.
+- **Ties on session name now sort ascending everywhere.** The recommendation ranking sorted names descending as a side effect of reversing its whole sort tuple, disagreeing with the headless ranking. The ascending order is kept.
+- **Logged-out sessions are never selection candidates.** `cdx select` without `--require-ready` could previously return one. `--require-ready` remains stricter still: it requires a confirmed `authenticated` state, so a session whose auth has never been checked is not offered to `cdx run --provider`.
+- `cdx status`'s recommendation line is labelled `Recommended:` instead of `Priority:`.
+- `cdx select --json`'s `selection_policy` is now a structured object rather than an underscore-joined string.
+
+## Fixes
+
+- `cdx --version` reported a stale release. `src/cli.py` restated the version as a fourth hardcoded copy alongside `VERSION`, `package.json`, and `pyproject.toml`, and nothing kept the four in step — it had been left at 0.12.4. The version is now resolved from the `VERSION` file in a checkout and from installed package metadata otherwise, and a test fails if any of the four (plus the README badge) disagree.
+- The release validator was left scraping a `VERSION = "..."` literal out of `src/cli.py`, which the fix above had removed. It resolved an empty string and rejected every release with "Missing release version in: src/cli.py" — inside the publish workflow, after the tag was already public. It now reads the resolved version, and a test fails if any declaration site stops yielding one.
+- Two tests still asserted the `--experimental-yolo` flag removed from ollama launches in 0.12.4 (GitHub issue #8); the launch behavior was already correct, the stale expectations are now aligned.
+- `format_json_error` honors an error's declared code instead of always re-deriving one from the message prefix, so structured argument errors keep their code when they reach the CLI entry point.
+- The detached-run test asserted the POSIX `start_new_session` unconditionally, so the Windows CI job failed on a code path that was correct. The assertion is now platform-aware, and Windows CI exercises the `creationflags` branch for the first time.
+
+## Review fixes
+
+Found by a review pass over the programmatic CLI work, before release:
+
+- The detached child's `CDX_RUN_ID` is consumed rather than read, so it is no longer inherited by the provider process. Left set, an agent making its own nested `cdx run` would have claimed the outer run's id, deleting its registry record and truncating its stdout, stderr, and transcript files.
+- The detached child receives the resolved absolute `--cwd`; a relative path would have resolved against the child's own working directory.
+- `--detach` now detaches correctly on Windows (`DETACHED_PROCESS | CREATE_NEW_PROCESS_GROUP`), and always re-invokes through `sys.executable -m` rather than `sys.argv[0]`, which is not reliably executable there.
+- `network_disabled_by_permission` now fires when no `--permission` is given at all — the most common invocation, where `codex exec` still applies its own sandboxed default. It previously exempted exactly the case it was written for.
+- `cdx run-tail` on a run that has not written its first byte returns `lines: []` instead of failing, so the launch-then-tail flow does not report a fatal error during that window. A missing output file on a *finished* run is still an error.
+- `run-tail` drops a partial leading line when the read window opens mid-line, rather than returning a fragment as if it were a whole line.
+- `cdx schema --json` publishes every error code the run commands emit, grouped by area, plus the warning codes; and `--reasoning-effort`/`--power` moved from `mutually_exclusive` to a new `must_match` group, since cdx accepts both when they agree.
+- An empty `--power ""` blames `--power` instead of `--reasoning-effort`.
+- `format_json_error` emits the same error field set as the run payload, so callers do not need two shapes.
+- The prompt a detached launch stages for its child is deleted once the child reads it, instead of leaving a permanent cleartext copy in the session log directory.
+
+## Validation
+
+- `npm run lint`
+- `npm test` — 565 tests.
+- CI green on ubuntu-latest and windows-latest.
+- End-to-end: detached launch returning `run_id`, `run-tail` against the in-flight run after the launcher exited, terminal status reached without a supervisor, and `runs --since` reporting the completion.
+- End-to-end: with one session at 80% availability and priority 0 and another at 40% and priority 90, `cdx select`, `cdx next`, and `cdx status` all name the second, and `cdx select` reports `decided on priority`.
+- The issue #8 condition reproduced against the new provider flag check: mapping `--experimental-yolo` for codex fails the check by name. All four provider CLIs verified against their real binaries.
+- `logics-manager lint --require-status`
+- `logics-manager audit --group-by-doc` — 0 blocking, 0 warnings.

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"
     }
   }
 }