cdx-manager 0.12.2 → 0.12.3

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.12.2-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.12.3-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.**
 
@@ -204,7 +204,9 @@ Release maintainer note:
 - Before publishing npm or PyPI packages, run `npm run release:validate`.
 - The release tag must match `package.json`, `pyproject.toml`, `src/cli.py`, and `VERSION`.
 - `checksums/release-archives.json` must include the matching `vX.Y.Z` entry with both `github_tarball_sha256` and `github_zip_sha256`.
-- Use `python3 scripts/update_release_checksums.py --tag vX.Y.Z` after the GitHub tag archives exist, commit the checksum update, attach that file to the tagged GitHub Release as `release-archives.json`, then publish packages only after `npm run release:validate`, `npm run lint`, and `npm test` pass.
+- Publishing a GitHub Release runs the checksum upload workflow: it regenerates `checksums/release-archives.json` for the release tag and uploads it as the `release-archives.json` asset with replacement enabled for safe reruns.
+- If the asset is missing or stale, repair it with `python3 scripts/update_release_checksums.py --tag vX.Y.Z`, then `gh release upload vX.Y.Z checksums/release-archives.json --clobber`.
+- Publish packages only after the checksum workflow succeeds and `npm run release:validate`, `npm run lint`, and `npm test` pass.
 
 ### Environment
 

package/changelogs/CHANGELOGS_0_12_3.md

@@ -0,0 +1,29 @@
+# CDX Manager 0.12.3
+
+## Highlights
+
+- GitHub Releases now trigger an automatic checksum asset workflow so `release-archives.json` is regenerated and uploaded for the published tag.
+- `cdx run` validation errors now explain what is wrong and how to list or create matching sessions.
+- Provider capacity or runtime failures now keep failed run records queryable instead of dropping them from the run registry.
+
+## Changes
+
+### Automated release checksum asset
+
+Publishing a GitHub Release now runs `.github/workflows/upload-release-checksums.yml`. The workflow checks out the release tag, regenerates `checksums/release-archives.json`, and uploads it as the `release-archives.json` release asset with replacement enabled for reruns.
+
+### More actionable run validation
+
+`cdx run` now returns specific guidance for unknown session references and invalid provider selections so users can recover with `cdx configs`, `cdx add`, or a corrected provider argument.
+
+### Queryable failed provider runs
+
+Provider run failures are now written to the run registry with failure metadata, preserving enough detail for later inspection even when the provider never starts successfully.
+
+## Validation
+
+- `npm run release:validate`
+- `npm run lint`
+- `npm test`
+- `logics-manager lint --require-status`
+- `logics-manager audit`

package/checksums/release-archives.json

@@ -156,6 +156,10 @@
     "v0.12.1": {
       "github_tarball_sha256": "87e3b11886a8e7fb10233d425f6a1986e62395c89049947678a50cfb20384278",
       "github_zip_sha256": "249f75eb240de7cc421f17579e0040d35eb06e3213568673f743c92191dda0f0"
+    },
+    "v0.12.2": {
+      "github_tarball_sha256": "5214f9f85f6bdc2c53bded938c91e28411de3c573bbcff81ebecb20dea6d99c2",
+      "github_zip_sha256": "8f447cdea9e921f7428c1c72db5a19f40f447a877bb2bc8dc1c8bd5e34daf070"
     }
   }
 }

package/package.json

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

package/src/cli.py

@@ -78,7 +78,7 @@ from .status_view import (
 )
 from .update_check import check_for_update, check_logics_manager_for_update
 
-VERSION = "0.12.2"
+VERSION = "0.12.3"
 
 # Public surface: this module is a facade. Names below are imported above
 # purely to be re-exported (consumed by tests and external callers); listing

package/src/cli_args.py

@@ -35,6 +35,13 @@ CAN_RESUME_USAGE = "Usage: cdx can-resume <name> [--json]"
 SELECT_USAGE = "Usage: cdx select --provider PROVIDER [--min-reasoning-effort minimal|low|medium|high|xhigh] [--min-power minimal|low|medium|high|xhigh] [--require-ready] [--refresh] --json"
 NEXT_USAGE = "Usage: cdx next [--json] [--refresh]"
 RUN_USAGE = "Usage: cdx run [session] --cwd PATH (--prompt-file PATH|--prompt TEXT) [--provider PROVIDER] [--model MODEL] [--kind assistant|code-review] [--reasoning-effort minimal|low|medium|high|xhigh] [--power minimal|low|medium|high|xhigh] [--permission review|default|auto|full|workspace-write|read-only|danger-full-access] [--timeout-seconds N] --json"
+RUN_JSON_REQUIRED = "cdx run: --json is required."
+RUN_TARGET_REQUIRED = "cdx run: specify a session name or --provider PROVIDER."
+RUN_SESSION_PROVIDER_CONFLICT = "cdx run: cannot specify both a session name and --provider."
+RUN_CWD_REQUIRED = "cdx run: --cwd PATH is required."
+RUN_PROMPT_SOURCE_REQUIRED = "cdx run: specify exactly one prompt source: --prompt TEXT or --prompt-file PATH."
+RUN_KIND_VALUES = ("assistant", "code-review")
+RUN_PERMISSION_VALUES = ("review", "default", "auto", "full", "workspace-write", "read-only", "danger-full-access")
 RUNS_USAGE = "Usage: cdx runs [--limit N] --json"
 RUN_STATUS_USAGE = "Usage: cdx run-status <run_id> --json"
 RUN_REPORT_USAGE = "Usage: cdx run-report <run_id> --json"
@@ -327,6 +334,21 @@ def _parse_timeout_seconds(value, usage=RUN_USAGE):
     return parsed
 
 
+def _parse_run_timeout_seconds(value):
+    try:
+        return _parse_timeout_seconds(value, RUN_USAGE)
+    except CdxError as error:
+        raise CdxError(f"cdx run: --timeout-seconds must be a positive number; got {value!r}.") from error
+
+
+def _parse_run_provider(value):
+    try:
+        return _parse_provider_filter(value, RUN_USAGE)
+    except CdxError as error:
+        allowed = "|".join(PROVIDERS)
+        raise CdxError(f"cdx run: invalid --provider {value!r}; allowed values: {allowed}.") from error
+
+
 def _normalize_run_permission(value):
     if value is None:
         return None
@@ -338,7 +360,8 @@ def _normalize_run_permission(value):
     }
     text = aliases.get(text, text)
     if text not in ("review", "default", "auto", "full"):
-        raise CdxError(RUN_USAGE)
+        allowed = "|".join(RUN_PERMISSION_VALUES)
+        raise CdxError(f"cdx run: invalid --permission {value!r}; allowed values: {allowed}.")
     return text
 
 
@@ -347,28 +370,29 @@ def _parse_run_args(args):
         "--cwd": {"key": "cwd", "type": "str", "default": None},
         "--prompt-file": {"key": "prompt_file", "type": "str", "default": None},
         "--prompt": {"key": "prompt", "type": "str", "default": None},
-        "--provider": {"key": "provider", "type": "str", "default": None, "transform": lambda value: _parse_provider_filter(value, RUN_USAGE)},
+        "--provider": {"key": "provider", "type": "str", "default": None, "transform": _parse_run_provider},
         "--model": {"key": "model", "type": "str", "default": None},
         "--kind": {"key": "kind", "type": "str", "default": "assistant"},
         "--reasoning-effort": {"key": "reasoning_effort", "type": "str", "default": None},
         "--power": {"key": "power", "type": "str", "default": None},
         "--permission": {"key": "permission", "type": "str", "default": None, "transform": _normalize_run_permission},
-        "--timeout-seconds": {"key": "timeout_seconds", "type": "str", "default": None, "transform": _parse_timeout_seconds},
+        "--timeout-seconds": {"key": "timeout_seconds", "type": "str", "default": None, "transform": _parse_run_timeout_seconds},
         "--json": {"key": "json", "type": "bool", "default": False},
     }, RUN_USAGE, positionals_key="names", max_positionals=1)
     if not parsed["json"]:
-        raise CdxError(RUN_USAGE)
+        raise CdxError(RUN_JSON_REQUIRED)
     name = parsed["names"][0] if parsed["names"] else None
     if name and parsed["provider"]:
-        raise CdxError(RUN_USAGE)
+        raise CdxError(RUN_SESSION_PROVIDER_CONFLICT)
     if not name and not parsed["provider"]:
-        raise CdxError(RUN_USAGE)
+        raise CdxError(RUN_TARGET_REQUIRED)
     if not parsed["cwd"]:
-        raise CdxError(RUN_USAGE)
+        raise CdxError(RUN_CWD_REQUIRED)
     if bool(parsed["prompt_file"]) == bool(parsed["prompt"]):
-        raise CdxError(RUN_USAGE)
-    if parsed["kind"] not in ("assistant", "code-review"):
-        raise CdxError(RUN_USAGE)
+        raise CdxError(RUN_PROMPT_SOURCE_REQUIRED)
+    if parsed["kind"] not in RUN_KIND_VALUES:
+        allowed = "|".join(RUN_KIND_VALUES)
+        raise CdxError(f"cdx run: invalid --kind {parsed['kind']!r}; allowed values: {allowed}.")
     effort = _normalize_reasoning_effort(
         reasoning_effort=parsed["reasoning_effort"],
         power=parsed["power"],

package/src/run_command.py

@@ -18,6 +18,8 @@ def run_cdx_error_code(error):
     message = str(error)
     if message.startswith("Usage:"):
         return "invalid_request"
+    if message.startswith("cdx run:"):
+        return "invalid_request"
     if message.startswith("Invalid cwd:"):
         return "invalid_cwd"
     if message.startswith("Session is disabled:"):
@@ -47,6 +49,30 @@ def run_payload_reasoning_effort(parsed, session):
     )
 
 
+def _tail_line(path, limit=4000):
+    if not path:
+        return None
+    try:
+        size = os.path.getsize(path)
+        with open(path, "rb") as handle:
+            handle.seek(max(0, size - limit))
+            text = handle.read().decode("utf-8", errors="replace")
+    except OSError:
+        return None
+    lines = [line.strip() for line in text.splitlines() if line.strip()]
+    if not lines:
+        return None
+    return lines[-1][:500]
+
+
+def _provider_failure_message(error, run_info, error_code):
+    base = str(error) if error else "Run failed."
+    if error_code != "provider_failed":
+        return base
+    detail = _tail_line(run_info.get("stderr_path")) or _tail_line(run_info.get("stdout_path"))
+    return f"{base}: {detail}" if detail else base
+
+
 def run_result_payload(api_schema_version, ok, parsed, session, run_info=None,
                        error=None, error_source=None, error_code=None):
     run_info = run_info or {}
@@ -55,6 +81,11 @@ def run_result_payload(api_schema_version, ok, parsed, session, run_info=None,
         if session else
         empty_usage()
     )
+    message = None if ok else (
+        _provider_failure_message(error, run_info, error_code)
+        if error_source == "provider"
+        else (str(error) if error else "Run failed.")
+    )
     return {
         "schema_version": api_schema_version,
         "ok": bool(ok),
@@ -77,7 +108,7 @@ def run_result_payload(api_schema_version, ok, parsed, session, run_info=None,
         "error": None if ok else {
             "source": error_source or "cdx",
             "code": error_code or "cdx_error",
-            "message": str(error) if error else "Run failed.",
+            "message": message,
             "provider_code": run_info.get("returncode") if error_source == "provider" else None,
         },
     }

package/src/update_manager.py

@@ -63,10 +63,10 @@ def detect_installation(package_root=None, prefix=None, base_prefix=None):
         return {"mode": "standalone", "package_root": str(root)}
     if _is_source_checkout(root):
         return {"mode": "source", "package_root": str(root)}
-    if _is_python_env(prefix=prefix, base_prefix=base_prefix):
-        return {"mode": "python", "package_root": str(root)}
     if (root / "package.json").exists():
         return {"mode": "npm", "package_root": str(root)}
+    if _is_python_env(prefix=prefix, base_prefix=base_prefix):
+        return {"mode": "python", "package_root": str(root)}
     return {"mode": "unknown", "package_root": str(root)}