cdx-manager 0.12.1 → 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.1-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
 
@@ -274,7 +276,7 @@ cdx disk profiles --candidates
 
 ### Next-Ready Notifications
 
-Use `cdx ready` when every useful assistant is cooling down and you want your terminal back. It is shorthand for `cdx notify --schedule --next-ready`: cdx picks the next known reset, registers a native OS notification, and exits immediately.
+Use `cdx ready` when every useful assistant is cooling down and you want your terminal back. It is shorthand for `cdx notify --schedule --next-ready`: cdx picks the next known reset, registers a native OS notification, and exits immediately. If no future reset is known, it exits successfully and explains that no notification was scheduled.
 
 ```bash
 cdx ready
@@ -372,7 +374,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] [--json]` | Import sessions from a bundle into the current `CDX_HOME` |
-| `cdx doctor [--json]` | Inspect CLI dependencies, provider CLI versions/capability hints, CDX_HOME permissions, missing state, orphan profiles, and pending quarantines |
+| `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 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 |

package/changelogs/CHANGELOGS_0_12_2.md

@@ -0,0 +1,28 @@
+# CDX Manager 0.12.2
+
+## Highlights
+
+- `cdx ready` now exits successfully when no future reset is known, clearly reporting that no notification was scheduled.
+- `cdx doctor` can filter diagnostics by severity with `--severity OK|WARN|FAIL`.
+- Unknown `cdx config <name>` sessions now explain how to inspect existing sessions or create the requested one.
+
+## Changes
+
+### Safer ready notifications
+
+When `cdx ready` cannot find an upcoming session reset, it returns a successful unscheduled result instead of failing. Named reset notifications with no known reset remain explicit errors.
+
+### Filterable diagnostics
+
+`cdx doctor --severity` accepts a comma-separated list of `OK`, `WARN`, and `FAIL` statuses. Text and JSON output retain accurate summaries for the filtered report.
+
+### Actionable configuration errors
+
+Unknown-session errors from `cdx config` now direct users to `cdx configs` to inspect available sessions and `cdx add <name>` to create one.
+
+## Validation
+
+- `npm run lint`
+- `npm test`
+- `logics-manager lint --require-status`
+- `logics-manager audit --group-by-doc`

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.1",
+  "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.1"
+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.1"
+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
@@ -216,7 +216,7 @@ def _print_help(use_color=False):
         f"  {_style('cdx clean profiles (--tmp|--old-logs DAYS) [--yes] [--json]', '36', use_color)}",
         f"  {_style('cdx export <file> [--include-auth] [--sessions a,b] [--passphrase-env VAR|--passphrase-stdin] [--force] [--json]', '36', use_color)}",
         f"  {_style('cdx import <file> [--sessions a,b] [--passphrase-env VAR|--passphrase-stdin] [--force|--merge] [--json]', '36', use_color)}",
-        f"  {_style('cdx doctor [--json]', '36', use_color)}",
+        f"  {_style('cdx doctor [--severity OK|WARN|FAIL[,OK|WARN|FAIL...]] [--json]', '36', use_color)}",
         f"  {_style('cdx repair [--dry-run] [--force] [--json]', '36', use_color)}",
         f"  {_style('cdx view [--json]', '36', use_color)}",
         f"  {_style('cdx update [all] [--check] [--yes] [--json] [--version TAG]', '36', use_color)}",

package/src/cli_args.py

@@ -12,7 +12,7 @@ from .errors import CdxError
 from .provider_runtime import _normalize_reasoning_effort
 
 STATUS_USAGE = "Usage: cdx status [--json] [--refresh|--cached] [--timeout SECONDS] | cdx status --small|-s [--refresh|--cached] [--timeout SECONDS] | cdx status <name> [--json] [--refresh|--cached] [--timeout SECONDS]"
-DOCTOR_USAGE = "Usage: cdx doctor [--json]"
+DOCTOR_USAGE = "Usage: cdx doctor [--severity OK|WARN|FAIL[,OK|WARN|FAIL...]] [--json]"
 DISK_USAGE = "Usage: cdx disk [profiles] [--candidates] [--json]"
 REPAIR_USAGE = "Usage: cdx repair [--dry-run] [--force] [--json]"
 UPDATE_USAGE = "Usage: cdx update [all] [--check] [--yes] [--json] [--version TAG]"
@@ -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"
@@ -46,6 +53,35 @@ def _parse_json_flag(args):
     return json_flag, cleaned
 
 
+def _parse_doctor_args(args):
+    parsed = {"json": False, "severity": None}
+    index = 0
+    while index < len(args):
+        arg = args[index]
+        if arg == "--json":
+            parsed["json"] = True
+            index += 1
+            continue
+        if arg == "--severity":
+            if parsed["severity"] is not None or index + 1 >= len(args):
+                raise CdxError(DOCTOR_USAGE)
+            value = args[index + 1]
+            index += 2
+        elif arg.startswith("--severity="):
+            if parsed["severity"] is not None:
+                raise CdxError(DOCTOR_USAGE)
+            value = arg.split("=", 1)[1]
+            index += 1
+        else:
+            raise CdxError(DOCTOR_USAGE)
+
+        values = [item.strip().upper() for item in value.split(",")]
+        if not values or any(item not in {"OK", "WARN", "FAIL"} for item in values):
+            raise CdxError(DOCTOR_USAGE)
+        parsed["severity"] = ",".join(dict.fromkeys(values))
+    return parsed
+
+
 def _parse_flag_args(args, schema, usage, positionals_key=None, max_positionals=0):
     parsed = {spec["key"]: spec.get("default") for spec in schema.values()}
     positionals = []
@@ -298,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
@@ -309,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
 
 
@@ -318,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/cli_commands.py

@@ -17,7 +17,6 @@ from .cli_args import (
     CAN_RESUME_USAGE,
     CONTEXT_USAGE,
     DISK_USAGE,
-    DOCTOR_USAGE,
     HANDOFF_USAGE,
     LAST_USAGE,
     MEMORY_USAGE,
@@ -33,6 +32,7 @@ from .cli_args import (
     _parse_config_args,
     _parse_configs_args,
     _parse_copy_args,
+    _parse_doctor_args,
     _parse_export_args,
     _parse_flag_args,
     _parse_history_args,
@@ -98,7 +98,7 @@ from .context_store import (
 )
 from .errors import CdxError
 from .fs_utils import atomic_write
-from .health import collect_health_report, format_health_report
+from .health import collect_health_report, filter_health_report, format_health_report
 from .notify import (
     format_notify_event,
     format_scheduled_notification,
@@ -1700,7 +1700,10 @@ def handle_config(rest, ctx):
     parsed = _parse_config_args(rest)
     session = ctx["service"]["get_session"](parsed["name"])
     if not session:
-        raise CdxError(f"Unknown session: {parsed['name']}")
+        raise CdxError(
+            f"Unknown session: {parsed['name']}. Run cdx configs to inspect existing sessions or "
+            f"cdx add {parsed['name']} to create it."
+        )
     message = f"Launch settings for {parsed['name']}"
     if parsed["json"]:
         _write_json(ctx, _json_success("config", message, session=session, launch=session.get("launch") or {}))
@@ -1893,17 +1896,15 @@ def handle_clean(rest, ctx):
 
 
 def handle_doctor(rest, ctx):
-    json_flag = "--json" in rest
-    unknown = [arg for arg in rest if arg != "--json"]
-    if unknown:
-        raise CdxError(DOCTOR_USAGE)
+    parsed = _parse_doctor_args(rest)
     report = collect_health_report(
         ctx["service"],
         ctx["service"]["base_dir"],
         env=ctx.get("env"),
         spawn_sync=ctx.get("spawn_sync"),
     )
-    if json_flag:
+    report = filter_health_report(report, parsed["severity"])
+    if parsed["json"]:
         _write_json(ctx, _json_success("doctor", "Collected health report", report=report))
     else:
         ctx["out"](f"{format_health_report(report, use_color=ctx['use_color'])}\n")

package/src/health.py

@@ -363,6 +363,19 @@ def summarize_health(issues):
     }
 
 
+def filter_health_report(report, severity):
+    if severity is None:
+        return report
+    severities = set(severity.split(","))
+    issues = [issue for issue in report["issues"] if issue["status"] in severities]
+    return {
+        **report,
+        "issues": issues,
+        "summary": summarize_health(issues),
+        "severity": severity,
+    }
+
+
 def format_health_report(report, use_color=False):
     rows = [["STATUS", "CHECK", "MESSAGE"]]
     for issue in report["issues"]:

package/src/notify.py

@@ -221,6 +221,13 @@ def schedule_notification_event(base_dir, parsed, event, spawn_sync=None, env=No
     now_fn = now_fn or time.time
     target_timestamp = event.get("target_timestamp")
     if target_timestamp is None:
+        if parsed["mode"] == "next-ready":
+            return {
+                "scheduled": False,
+                "backend": "none",
+                "message": event["message"],
+                "target_timestamp": None,
+            }
         raise CdxError(f"Cannot schedule notification: {event['message']}")
     if target_timestamp <= now_fn():
         return {

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