cdx-manager 0.6.4 → 0.7.0

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.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.7.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.**
 
@@ -51,7 +51,7 @@ One command to launch any session. Zero auth juggling.
 
 ## Technical Overview
 
-- Python 3.9+, zero runtime dependencies.
+- Python 3.9+.
 - Environment isolation per session:
   - Codex sessions override `CODEX_HOME` to a dedicated profile directory.
   - Claude sessions override `HOME` to a dedicated profile directory and disable Claude Code commit co-author attribution by default.
@@ -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.4 sh install.sh
+CDX_VERSION=v0.7.0 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 `run_id`, selected `session`, `provider`, `exit_code`, `duration_seconds`, absolute `transcript_path`, `stdout_path`, `stderr_path`, and normalized usage token fields. Token counts are `null` when the provider does not expose them.
+
+`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_6_5.md

@@ -0,0 +1,35 @@
+# Changelog (`0.6.4 -> 0.6.5`)
+
+Release date: 2026-05-29
+
+## Installer Integrity
+
+- Fixed standalone installer checksum resolution so the Unix installer can validate published GitHub archive checksums correctly.
+- Added regression coverage for the release checksum lookup path used by the standalone installer.
+
+## Claude Authentication
+
+- Preserved the captured Claude setup-token transcript when token extraction fails, making failed login setup recoverable and easier to inspect.
+- Reordered Claude status handling so authentication is checked before refreshing usage, avoiding noisy usage refresh failures when Claude credentials are absent or invalid.
+
+## Codex Authentication
+
+- Hardened Codex auth detection so an empty or unusable `auth.json` is no longer treated as an authenticated session.
+- Added coverage for usable-token validation instead of relying on file presence alone.
+
+## Auth Bundle Security
+
+- Replaced the previous homegrown auth bundle encryption with AEAD encryption via `cryptography`.
+- Added wrong-passphrase and auth bundle regression tests for the new encrypted bundle format.
+- Updated CI and publish workflows to install Python package dependencies before running Python-backed lint, tests, and version validation.
+
+## Release Metadata and Documentation
+
+- Updated package metadata, CLI version output, README badge, pinned installer example, and release changelog to `v0.6.5`.
+
+## Validation and Regression Evidence
+
+- `npm run lint`
+- `npm test`
+- `python -m build --sdist --wheel`
+- `npm pack --dry-run`

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/checksums/release-archives.json

@@ -20,6 +20,14 @@
     "v0.6.3": {
       "github_tarball_sha256": "539bc299fe2211cddcbe58db71a859ebbd1cb76aec254f6feef501fc038d7c62",
       "github_zip_sha256": "138c7c67ea1b512d71ed745559f8eed395accb9a06b3ed9d82c3ccc454aba12b"
+    },
+    "v0.6.4": {
+      "github_tarball_sha256": "f7c83dd1ae7506cf1ae6420e718a285f4dc96a10fb3a19e24cc17e79d75a46b4",
+      "github_zip_sha256": "d602800cf6b54f1e0adea751cc6b686ab2fc4a224715ade94f761df2ff7da2af"
+    },
+    "v0.6.5": {
+      "github_tarball_sha256": "f2280917ea75b5ae1e99a99b011f09704d89b1a7ae42497f5093e6fff9f814d9",
+      "github_zip_sha256": "0b8491037310ed82cf44419d0de887bc0f768c6690c69153992fc4d5cda69676"
     }
   }
 }

package/install.sh

@@ -34,7 +34,7 @@ sha256_file() {
 
 resolve_expected_sha256() {
   curl -fsSL "$CHECKSUMS_URL" |
-    python3 - "$1" <<'PY'
+    python3 -c '
 import json
 import sys
 
@@ -48,7 +48,7 @@ release = (payload.get("releases") or {}).get(tag) or {}
 value = release.get("github_tarball_sha256")
 if value:
     print(value)
-PY
+' "$1"
 }
 
 if [ -z "$VERSION" ]; then

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "cdx-manager",
-  "version": "0.6.4",
+  "version": "0.7.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.6.4"
+version = "0.7.0"
 description = "Terminal session manager for Codex and Claude accounts."
 readme = "README.md"
 requires-python = ">=3.9"
@@ -26,7 +26,7 @@ classifiers = [
   "Topic :: Software Development",
   "Topic :: Terminals",
 ]
-dependencies = []
+dependencies = ["cryptography>=42"]
 
 [project.urls]
 Homepage = "https://github.com/AlexAgo83/cdx-manager"

package/src/backup_bundle.py

@@ -11,10 +11,13 @@ from .errors import CdxError
 BUNDLE_SCHEMA_VERSION = 1
 _SALT_BYTES = 16
 _NONCE_BYTES = 16
+_AEAD_NONCE_BYTES = 12
 _SCRYPT_N = 2 ** 14
 _SCRYPT_R = 8
 _SCRYPT_P = 1
 _PBKDF2_ITERATIONS = 200000
+_AEAD_ALGORITHM = "aes-256-gcm"
+_LEGACY_ALGORITHM = "sha256-xor-hmac"
 
 
 def _now_iso():
@@ -68,6 +71,22 @@ def _derive_keys(passphrase, salt):
     return key_material[:32], key_material[32:]
 
 
+def _derive_aead_key(passphrase, salt):
+    enc_key, _mac_key = _derive_keys(passphrase, salt)
+    return enc_key
+
+
+def _load_aesgcm():
+    try:
+        from cryptography.hazmat.primitives.ciphers.aead import AESGCM
+    except ImportError as error:
+        raise CdxError(
+            "Auth bundle encryption requires the Python package 'cryptography'. "
+            "Install cdx-manager through pipx/uv/pip, or install cryptography for the Python used by cdx."
+        ) from error
+    return AESGCM
+
+
 def _xor_keystream(data, key, nonce):
     output = bytearray()
     counter = 0
@@ -90,14 +109,14 @@ def encode_bundle(payload, include_auth=False, passphrase=None):
     }
     if include_auth:
         salt = os.urandom(_SALT_BYTES)
-        nonce = os.urandom(_NONCE_BYTES)
-        enc_key, mac_key = _derive_keys(passphrase, salt)
-        ciphertext = _xor_keystream(payload_bytes, enc_key, nonce)
-        mac = hmac.new(mac_key, nonce + ciphertext, hashlib.sha256).digest()
+        nonce = os.urandom(_AEAD_NONCE_BYTES)
+        aesgcm = _load_aesgcm()(_derive_aead_key(passphrase, salt))
+        ciphertext = aesgcm.encrypt(nonce, payload_bytes, None)
         wrapper.update({
+            "encryption": _AEAD_ALGORITHM,
+            "kdf": "scrypt" if hasattr(hashlib, "scrypt") else "pbkdf2-hmac-sha256",
             "salt": _b64_encode(salt),
             "nonce": _b64_encode(nonce),
-            "hmac_sha256": _b64_encode(mac),
             "payload": _b64_encode(ciphertext),
         })
     else:
@@ -116,13 +135,23 @@ def decode_bundle(data, passphrase=None):
     if encrypted:
         salt = _b64_decode(wrapper.get("salt", ""))
         nonce = _b64_decode(wrapper.get("nonce", ""))
-        expected_mac = _b64_decode(wrapper.get("hmac_sha256", ""))
         ciphertext = _b64_decode(payload_b64)
-        enc_key, mac_key = _derive_keys(passphrase, salt)
-        actual_mac = hmac.new(mac_key, nonce + ciphertext, hashlib.sha256).digest()
-        if not hmac.compare_digest(actual_mac, expected_mac):
-            raise CdxError("Invalid bundle passphrase or corrupted bundle.")
-        payload_bytes = _xor_keystream(ciphertext, enc_key, nonce)
+        algorithm = wrapper.get("encryption") or _LEGACY_ALGORITHM
+        if algorithm == _AEAD_ALGORITHM:
+            aesgcm = _load_aesgcm()(_derive_aead_key(passphrase, salt))
+            try:
+                payload_bytes = aesgcm.decrypt(nonce, ciphertext, None)
+            except Exception as error:
+                raise CdxError("Invalid bundle passphrase or corrupted bundle.") from error
+        elif algorithm == _LEGACY_ALGORITHM:
+            expected_mac = _b64_decode(wrapper.get("hmac_sha256", ""))
+            enc_key, mac_key = _derive_keys(passphrase, salt)
+            actual_mac = hmac.new(mac_key, nonce + ciphertext, hashlib.sha256).digest()
+            if not hmac.compare_digest(actual_mac, expected_mac):
+                raise CdxError("Invalid bundle passphrase or corrupted bundle.")
+            payload_bytes = _xor_keystream(ciphertext, enc_key, nonce)
+        else:
+            raise CdxError("Unsupported bundle encryption algorithm.")
     else:
         payload_bytes = _b64_decode(payload_b64)
 

package/src/claude_refresh.py

@@ -38,6 +38,7 @@ def _refresh_claude_sessions(service, refresh_fn=None, target_names=None, force=
         s for s in sessions
         if s["provider"] == PROVIDER_CLAUDE
         and s.get("enabled", True) is not False
+        and (s.get("auth") or {}).get("status") != "logged_out"
         and (not target_names or s["name"] in target_names)
         and (force or _is_stale(s, ttl_seconds=ttl_seconds))
     ]

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.4"
+VERSION = "0.7.0"
 
 
 # ---------------------------------------------------------------------------
@@ -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)