cdx-manager 0.12.2 → 0.12.4

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.4-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
 
@@ -371,7 +373,7 @@ cdx history --summary --from 2026-05-01 --to 2026-05-28
 | `cdx disk [profiles] [--candidates] [--json]` | Measure `CDX_HOME`; `profiles` includes per-profile breakdown, and `--candidates` reports reclaimable temporary caches and old logs with evidence |
 | `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 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 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 |
@@ -525,10 +527,10 @@ cdx import backup-auth.cdx --passphrase-env CDX_BUNDLE_PASSPHRASE
 
 Notes:
 
-- `--include-auth` is encrypted, requires a passphrase, and exports only provider credential files rather than full profile caches or logs.
+- `--include-auth` is encrypted, requires a passphrase, and exports only provider credential files rather than full profile caches, logs, or installed plugins.
 - Without `--passphrase-env`, `cdx` prompts in an interactive terminal. Non-interactive callers can pass `--passphrase-stdin` to read the passphrase from stdin (one line) instead of exposing it in the child environment.
 - `--sessions work,perso` exports or imports only a subset.
-- `--force` allows overwriting existing destination sessions during import or replacing an existing bundle file during export. Import refuses to overwrite existing sessions from a bundle without auth payloads unless `--allow-authless-force` is also passed.
+- `--force` allows overwriting existing destination sessions during import or replacing an existing bundle file during export. Import preserves detected local `plugins/` state when the bundle does not provide it, and refuses to overwrite existing sessions from a bundle without auth payloads unless `--allow-authless-force` is also passed.
 - Auth bundles contain credentials. Treat them like secrets and delete them after transfer.
 
 ---

package/changelogs/CHANGELOGS_0_12_3.md

@@ -0,0 +1,34 @@
+# 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 import --force` now preserves detected local Codex plugin state while refreshing sessions from auth-bearing bundles.
+- `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.
+
+### Force import plugin preservation
+
+Auth-bearing force imports now keep local `plugins/` state when the incoming bundle does not include plugin files, so refreshing credentials does not silently remove locally installed Codex plugins.
+
+### 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/changelogs/CHANGELOGS_0_12_4.md

@@ -0,0 +1,18 @@
+# CDX Manager 0.12.4
+
+## Highlights
+
+- `cdx import --force` now preserves local Codex plugins when refreshing from bundles that do not include plugin files.
+
+## Changes
+
+### Force import plugin preservation
+
+Force imports of auth-bearing bundles keep detected local `plugins/` state instead of deleting it when the incoming bundle omits plugin files. This keeps locally installed Codex plugins available after credential refresh imports.
+
+## Validation
+
+- `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.4",
   "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.4"
 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.4"
 
 # Public surface: this module is a facade. Names below are imported above
 # purely to be re-exported (consumed by tests and external callers); listing
@@ -215,7 +215,7 @@ def _print_help(use_color=False):
         f"  {_style('cdx clean [name] [--yes] [--json]', '36', use_color)}",
         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 import <file> [--sessions a,b] [--passphrase-env VAR|--passphrase-stdin] [--force|--merge] [--allow-authless-force] [--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)}",

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/session_service.py

@@ -78,6 +78,7 @@ CLAUDE_STATUS_CACHE_TTL_SECONDS = 10 * 60
 # Each live Codex probe spawns app-server, which can refresh+rotate the OAuth
 # token. Cache longer so routine status calls don't keep triggering refreshes.
 CODEX_STATUS_CACHE_TTL_SECONDS = 5 * 60
+_FORCE_IMPORT_PRESERVED_PROFILE_PATHS = ("plugins",)
 STATUS_PROBE_TIMEOUT_SECONDS = 5
 MAX_STATUS_WORKERS = 8
 LAUNCH_POWER_VALUES = {"minimal", "low", "medium", "high", "xhigh"}
@@ -1427,6 +1428,26 @@ def create_session_service(options=None):
         else:
             store["remove_session"](name)
 
+    def _force_import_preserved_profile_paths(session_root):
+        return [rel_path for rel_path in _FORCE_IMPORT_PRESERVED_PROFILE_PATHS if os.path.exists(os.path.join(session_root, rel_path))]
+
+    def _restore_force_import_profile_paths(name, backup_root, session_root, rel_paths):
+        if not backup_root:
+            return
+        for rel_path in rel_paths:
+            source_path = os.path.join(backup_root, rel_path)
+            dest_path = os.path.join(session_root, rel_path)
+            if not os.path.exists(source_path) or os.path.exists(dest_path):
+                continue
+            try:
+                if os.path.isdir(source_path) and not os.path.islink(source_path):
+                    shutil.copytree(source_path, dest_path)
+                else:
+                    _ensure_private_dir(os.path.dirname(dest_path))
+                    shutil.copy2(source_path, dest_path)
+            except Exception as error:
+                raise CdxError(f"Could not restore local plugin state for session {name}: {rel_path}") from error
+
     def import_bundle(
         file_path,
         passphrase=None,
@@ -1479,9 +1500,11 @@ def create_session_service(options=None):
             backup_root = None
             old_record = None
             old_state = None
+            preserved_profile_paths = []
             if is_existing and force:
                 old_record = store["get_session"](name)
                 old_state = store["read_session_state"](name)
+                preserved_profile_paths = _force_import_preserved_profile_paths(session_root)
                 if os.path.exists(session_root):
                     backup_root = tempfile.mkdtemp(prefix=f".{_encode(name)}.import.", dir=os.path.dirname(session_root))
                     os.rmdir(backup_root)
@@ -1535,6 +1558,7 @@ def create_session_service(options=None):
                     _ensure_private_dir(os.path.dirname(dest_path))
                     # Decrypted credentials: 0o600 from creation, no umask window.
                     atomic_write(dest_path, item["content"], mode=0o600)
+                _restore_force_import_profile_paths(name, backup_root, session_root, preserved_profile_paths)
             except Exception:
                 _restore_import_backup(name, backup_root, session_root, old_record, old_state)
                 raise

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