cdx-manager 0.6.5 → 0.7.1

package/README.md

@@ -1,6 +1,6 @@
 # CDX Manager
 
-[![License](https://img.shields.io/badge/license-MIT-4C8BF5)](LICENSE) ![Version](https://img.shields.io/badge/version-v0.6.5-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.7.1-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.**
 
@@ -134,7 +134,7 @@ For a specific version:
 
 ```bash
 curl -fsSL https://raw.githubusercontent.com/AlexAgo83/cdx-manager/main/install.sh -o install.sh
-CDX_VERSION=v0.6.5 sh install.sh
+CDX_VERSION=v0.7.1 sh install.sh
 ```
 
 From source:
@@ -263,6 +263,7 @@ cdx set work --power medium --permission full --fast off
 cdx set personal --power low --permission review
 cdx set --sessions all --permission auto
 cdx set --provider ollama --model llama3.2
+cdx set work --priority 80
 cdx power all low
 cdx perm provider:claude review
 cdx model provider:ollama llama3.2
@@ -275,12 +276,13 @@ Those values are stored on the session and reapplied every time you run `cdx wor
 cdx unset work --power
 cdx unset --sessions work,personal --fast
 cdx unset --provider claude --permission
+cdx unset work --priority
 cdx unset work --all
 cdx power all default
 cdx model provider:ollama default
 ```
 
-`--power` maps to Codex `model_reasoning_effort` and Claude `--effort`. `--permission` maps to provider-native permission flags. `--fast on` uses low effort when no explicit power is set.
+`--power` maps to Codex `model_reasoning_effort` and Claude `--effort`. `--permission` maps to provider-native permission flags. `--fast on` uses low effort when no explicit power is set. `--priority` is a 0..100 selector preference used as a tie-breaker after readiness and availability.
 
 ### Launch History
 
@@ -317,8 +319,8 @@ cdx history --summary --from 2026-05-01 --to 2026-05-28
 | `cdx enable <name> [--json]` | Re-enable a disabled session |
 | `cdx config <name> [--json]` | Show persistent launch settings for a session |
 | `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 low\|medium\|high\|xhigh\|max] [--permission review\|default\|auto\|full] [--fast on\|off] [--model MODEL] [--json]` | Persist launch settings for one or more sessions |
-| `cdx unset <name>\|--sessions all\|a,b\|--provider PROVIDER (--power\|--permission\|--fast\|--model\|--all) [--json]` | Remove persisted launch settings and fall back to provider defaults |
+| `cdx set <name>\|--sessions all\|a,b\|--provider PROVIDER [--power low\|medium\|high\|xhigh\|max] [--permission review\|default\|auto\|full] [--fast 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\|--model\|--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 context show\|path\|init\|edit\|clear\|set [text...] [--json]` | Manage the shared Markdown context for the current workspace |
@@ -334,6 +336,8 @@ cdx history --summary --from 2026-05-01 --to 2026-05-28
 | `cdx ready [--refresh] [--json]` | Schedule an OS notification for the next cooling-down assistant that becomes ready, then return immediately |
 | `cdx notify <name> --at-reset [--poll seconds] [--once] [--schedule] [--refresh] [--json]` | Wait for a session reset time or schedule an OS wake-up notification when due |
 | `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 select --provider PROVIDER [--min-reasoning-effort low\|medium\|high] [--min-power low\|medium\|high] [--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 low\|medium\|high] [--power low\|medium\|high] [--permission MODE] [--timeout-seconds N] --json` | Run one headless task and return a stable JSON result |
 | `cdx status [--json] [--refresh]` | Show token usage table for all sessions; JSON returns a versioned payload with structured warnings |
 | `cdx status --small [--refresh]` / `cdx status -s [--refresh]` | Show compact token usage table without provider, blocking quota, credits, and updated columns |
 | `cdx status <name> [--json] [--refresh]` | Show detailed usage breakdown for one session |
@@ -371,6 +375,8 @@ Commands with machine-readable output:
 - `cdx update --json`
 - `cdx ready --json`
 - `cdx notify ... --json`
+- `cdx select ... --json`
+- `cdx run ... --json`
 
 Success payloads follow a shared envelope:
 
@@ -387,7 +393,7 @@ Success payloads follow a shared envelope:
 }
 ```
 
-Errors use a shared stderr JSON envelope whenever `--json` is present:
+Most commands use a shared stderr JSON envelope for errors whenever `--json` is present:
 
 ```json
 {
@@ -401,10 +407,44 @@ Errors use a shared stderr JSON envelope whenever `--json` is present:
 }
 ```
 
-`status --json` and similar commands also use the same envelope and place non-fatal issues in `warnings` instead of mixing plain-text diagnostics into `stderr`.
+`status --json` and similar commands also use the same envelope and place non-fatal issues in `warnings` instead of mixing plain-text diagnostics into `stderr`. `cdx run --json` is the exception: it always writes one final JSON payload to stdout, including cdx-side and provider-start errors, so supervisors can parse a single result stream while provider stdout and stderr are captured to files.
 
 This makes `cdx-manager` usable from editor plugins, scripts, and desktop apps without scraping human-readable terminal output.
 
+### Headless Runs
+
+`cdx run` is designed for supervisors such as Orchestia. In `--json` mode, stdout contains only the final JSON payload; provider stdout and stderr are captured to files.
+
+```bash
+cdx run codex-work \
+  --cwd /path/to/workspace \
+  --prompt-file task_prompt.md \
+  --model gpt-5.3-codex \
+  --reasoning-effort low \
+  --permission workspace-write \
+  --timeout-seconds 1800 \
+  --json
+```
+
+Use provider-based auto-selection when the caller wants cdx-manager to pick the account:
+
+```bash
+cdx run \
+  --provider codex \
+  --cwd /path/to/workspace \
+  --prompt "Summarize the repo status." \
+  --reasoning-effort low \
+  --json
+```
+
+The result includes `launcher: "cdx"`, `run_id`, selected `session`, `provider`, `exit_code`, `duration_seconds`, absolute `transcript_path`, `stdout_path`, `stderr_path`, and normalized usage token fields. Codex headless runs use `codex exec --json`; Claude headless runs use `claude --print --output-format json`. Token counts are `null` when the provider does not expose a supported JSON or JSONL usage shape.
+
+`cdx select` exposes the same session selection logic directly:
+
+```bash
+cdx select --provider codex --min-reasoning-effort low --require-ready --json
+```
+
 ---
 
 ## Backup And Restore

package/changelogs/CHANGELOGS_0_7_0.md

@@ -0,0 +1,49 @@
+# Changelog (`0.6.5 -> 0.7.0`)
+
+Release date: 2026-05-29
+
+## Headless Automation
+
+- Added `cdx run --json` as a headless execution contract for automation clients such as Orchestia.
+- Added explicit session execution, provider-based auto-selection, inline prompt and prompt-file support, working-directory validation, timeout handling, and stable run metadata.
+- Kept JSON mode stdout reserved for the final response so callers can parse command output without terminal UI noise.
+- Returned structured cdx-side and provider-side error envelopes for missing provider CLIs, invalid launch inputs, provider start failures, disabled sessions, and reasoning validation errors.
+
+## Session Selection
+
+- Added `cdx select --json` with deterministic ranking from provider match, readiness, cooldown, quota health, configured priority, reasoning capability, and session name.
+- Reused the same selector from `cdx run --provider ...`.
+- Added priority handling improvements, including configured-priority tie-breaking and clearing selection priority.
+- Allowed ready selection for local providers where remote quota signals are not applicable.
+
+## Reasoning Effort
+
+- Added provider-neutral `--reasoning-effort low|medium|high` handling.
+- Kept `--power` as a compatibility alias and rejected conflicting values with cdx-sourced JSON errors.
+- Mapped normalized effort into Codex launch options while leaving clear extension points for other providers.
+
+## Artifacts and Diagnostics
+
+- Added transcript, stdout, and stderr artifact reporting for headless runs.
+- Returned absolute artifact paths and normalized nullable token usage fields on success and failure responses.
+- Hardened artifact and timeout tests to cover provider failures and unknown usage.
+
+## Documentation and Release Readiness
+
+- Documented the Orchestia headless delivery, headless CLI options, selection reasons, and JSON error stream behavior.
+- Completed Logics release-gate documentation with rollback coverage, project changelog, release notes, duplicate triage, and release gate artifacts.
+- Carried forward the `v0.6.5` release checksum metadata so standalone installer integrity checks can resolve the previous release.
+
+## Release Metadata
+
+- Updated package metadata, CLI version output, README badge, pinned installer example, and release changelog to `v0.7.0`.
+
+## Validation and Regression Evidence
+
+- `python -m py_compile bin/cdx src/*.py test/test_*_py.py`
+- `python -m unittest discover -s test -p 'test_*_py.py'`
+- `npm run lint`
+- `npm test`
+- `npm pack --dry-run`
+- `python -m build`
+- `python -m twine check dist/*`

package/changelogs/CHANGELOGS_0_7_1.md

@@ -0,0 +1,41 @@
+# Changelog (`0.7.0 -> 0.7.1`)
+
+Release date: 2026-05-29
+
+## Headless Automation
+
+- Switched `cdx run --json` Codex execution to the provider-native `codex exec --json` path so headless runs no longer depend on an interactive terminal launch mode.
+- Switched Claude headless execution to `claude --print --output-format json` while preserving isolated auth homes, model selection, permission mode, and effort mapping.
+- Preserved Codex unattended `auto` permission behavior in headless mode with an explicit `approval_policy="never"` config override.
+- Kept provider stdout and stderr captured in artifact files while cdx stdout remains reserved for the final JSON payload.
+
+## JSON Contract
+
+- Added top-level `launcher: "cdx"` to `cdx run --json` result payloads so subprocess callers can identify cdx-manager responses directly.
+- Ensured `launcher: "cdx"` is also present when provider auto-selection cannot find a suitable session.
+- Added conservative token usage extraction for supported Codex and Claude JSON or JSONL stdout artifact shapes.
+- Preserved all-null token usage when artifacts are missing, malformed, unsupported, or do not expose trusted usage data.
+
+## Status Display
+
+- Clamped Claude rate-limit percentage calculations to the `0..100` range so over-limit provider utilization cannot display negative remaining availability.
+- Clamped cached status percentages defensively so already-persisted invalid values render as valid availability values.
+- Colored fully depleted or invalid low availability as red and high availability above 80% as bright cyan.
+
+## Planning Docs
+
+- Added and completed Logics request, backlog items, and tasks for Orchestia headless token usage and provider-native launch modes.
+
+## Release Metadata
+
+- Updated package metadata, CLI version output, README badge, pinned installer example, and release changelog to `v0.7.1`.
+
+## Validation and Regression Evidence
+
+- `python -m unittest discover -s test -p 'test_*_py.py'`
+- `npm run lint`
+- `npm test`
+- `npm pack --dry-run`
+- `python -m build`
+- `python -m twine check dist/*`
+- `python3 -m logics_manager lint --require-status`

package/checksums/release-archives.json

@@ -24,6 +24,14 @@
     "v0.6.4": {
       "github_tarball_sha256": "f7c83dd1ae7506cf1ae6420e718a285f4dc96a10fb3a19e24cc17e79d75a46b4",
       "github_zip_sha256": "d602800cf6b54f1e0adea751cc6b686ab2fc4a224715ade94f761df2ff7da2af"
+    },
+    "v0.6.5": {
+      "github_tarball_sha256": "f2280917ea75b5ae1e99a99b011f09704d89b1a7ae42497f5093e6fff9f814d9",
+      "github_zip_sha256": "0b8491037310ed82cf44419d0de887bc0f768c6690c69153992fc4d5cda69676"
+    },
+    "v0.7.0": {
+      "github_tarball_sha256": "c80231884bf20c9ae74144a1ec16e0685c2fdac67d7d93a3c6219c5ac6fc14dd",
+      "github_zip_sha256": "0e6af29e59d3a93a07e07656d6c0c93803a674e65830ef33fa2322649b7139c2"
     }
   }
 }

package/package.json

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

package/src/claude_usage.py

@@ -87,6 +87,15 @@ def _format_reset_date(unix_seconds):
     return f"{MONTH_ABBR[dt.month - 1]} {dt.day} {str(dt.hour).zfill(2)}:{str(dt.minute).zfill(2)}"
 
 
+def _remaining_from_utilization(value):
+    if value is None:
+        return None
+    try:
+        return max(0, min(100, round((1 - float(value)) * 100)))
+    except (TypeError, ValueError):
+        return None
+
+
 def _read_http_error_message(error):
     try:
         body = error.read().decode("utf-8", errors="replace")
@@ -159,8 +168,8 @@ def fetch_claude_rate_limit_headers(access_token):
     reset_at = reset_week_at or reset_5h_at
 
     return {
-        "remaining_5h_pct": round((1 - utilization_5h) * 100) if utilization_5h is not None else None,
-        "remaining_week_pct": round((1 - utilization_7d) * 100) if utilization_7d is not None else None,
+        "remaining_5h_pct": _remaining_from_utilization(utilization_5h),
+        "remaining_week_pct": _remaining_from_utilization(utilization_7d),
         "reset_5h_at": reset_5h_at,
         "reset_week_at": reset_week_at,
         "reset_at": reset_at,

package/src/cli.py

@@ -28,6 +28,8 @@ from .cli_commands import (
     handle_remove,
     handle_repair,
     handle_rename,
+    handle_run,
+    handle_select,
     handle_status,
     handle_set,
     handle_unset,
@@ -55,7 +57,7 @@ from .status_view import (
 )
 from .update_check import check_for_update
 
-VERSION = "0.6.5"
+VERSION = "0.7.1"
 
 
 # ---------------------------------------------------------------------------
@@ -72,11 +74,13 @@ def _print_help(use_color=False):
         f"  {_style('cdx status [--json] [--refresh]', '36', use_color)}",
         f"  {_style('cdx status --small|-s [--refresh]', '36', use_color)}",
         f"  {_style('cdx status <name> [--json] [--refresh]', '36', use_color)}",
+        f"  {_style('cdx select --provider PROVIDER [--min-reasoning-effort low|medium|high] [--min-power low|medium|high] [--require-ready] [--refresh] --json', '36', use_color)}",
+        f"  {_style('cdx run [session] --cwd PATH (--prompt-file PATH|--prompt TEXT) [--provider PROVIDER] [--model MODEL] [--reasoning-effort low|medium|high] [--power low|medium|high] [--permission review|default|auto|full|workspace-write|read-only|danger-full-access] [--timeout-seconds N] --json', '36', use_color)}",
         f"  {_style('cdx context show|path|init|edit|clear|set [text...] [--json]', '36', use_color)}",
         f"  {_style('cdx config <name> [--json]', '36', use_color)}",
         f"  {_style('cdx power|perm|fast|model <name|all|provider:PROVIDER|a,b> <value|default> [--json]', '36', use_color)}",
-        f"  {_style('cdx set <name>|--sessions all|a,b|--provider PROVIDER [--power low|medium|high|xhigh|max] [--permission review|default|auto|full] [--fast on|off] [--model MODEL] [--json]', '36', use_color)}",
-        f"  {_style('cdx unset <name>|--sessions all|a,b|--provider PROVIDER (--power|--permission|--fast|--model|--all) [--json]', '36', use_color)}",
+        f"  {_style('cdx set <name>|--sessions all|a,b|--provider PROVIDER [--power low|medium|high|xhigh|max] [--permission review|default|auto|full] [--fast on|off] [--model MODEL] [--priority 0..100] [--json]', '36', use_color)}",
+        f"  {_style('cdx unset <name>|--sessions all|a,b|--provider PROVIDER (--power|--permission|--fast|--model|--priority|--all) [--json]', '36', use_color)}",
         f"  {_style('cdx history [name] [--limit N] [--summary] [--since 7d|today|DATE] [--from DATE] [--to DATE] [--json]', '36', use_color)}",
         f"  {_style('cdx last [--json]', '36', use_color)}",
         f"  {_style('cdx handoff <name> [--json]', '36', use_color)}",
@@ -228,12 +232,13 @@ def main(argv, options=None):
         "service": service,
         "signal_emitter": signal_emitter,
         "spawn": spawn,
+        "spawn_headless": options.get("spawn_headless"),
         "spawn_sync": spawn_sync,
         "stdin_is_tty": stdin_is_tty,
         "version": VERSION,
         "cwd": options.get("cwd") or os.getcwd(),
         "update_notice": _get_update_notice(service, env, options) if command not in (
-            "add", "cp", "ren", "rename", "mv", "rmv", "clean", "doctor", "repair", "update", "ready", "notify", "context", "config", "set", "unset", "power", "perm", "fast", "model", "history", "handoff", "login", "logout", "disable", "enable", "export", "import", "help", "version"
+            "add", "cp", "ren", "rename", "mv", "rmv", "clean", "doctor", "repair", "update", "ready", "notify", "context", "config", "set", "unset", "power", "perm", "fast", "model", "history", "handoff", "login", "logout", "disable", "enable", "export", "import", "select", "run", "help", "version"
         ) else None,
         "use_color": use_color,
     }
@@ -309,6 +314,12 @@ def main(argv, options=None):
     if command == "status":
         return handle_status(rest, ctx)
 
+    if command == "select":
+        return handle_select(rest, ctx)
+
+    if command == "run":
+        return handle_run(rest, ctx)
+
     if command == "login":
         return handle_login(rest, ctx)