cdx-manager 0.7.0 → 0.7.2

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.7.0-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.2-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.7.0 sh install.sh
+CDX_VERSION=v0.7.2 sh install.sh
 ```
 
 From source:
@@ -264,6 +264,7 @@ 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 set work --rtk on
 cdx power all low
 cdx perm provider:claude review
 cdx model provider:ollama llama3.2
@@ -277,12 +278,13 @@ cdx unset work --power
 cdx unset --sessions work,personal --fast
 cdx unset --provider claude --permission
 cdx unset work --priority
+cdx unset work --rtk
 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. `--priority` is a 0..100 selector preference used as a tie-breaker after readiness and availability.
+`--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. `--rtk on` injects a launch instruction that encourages assistants to use RTK (`rtk <command>`) for noisy terminal commands when RTK is available, while keeping raw commands for exact output.
 
 ### Launch History
 
@@ -319,8 +321,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] [--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 set <name>\|--sessions all\|a,b\|--provider PROVIDER [--power low\|medium\|high\|xhigh\|max] [--permission review\|default\|auto\|full] [--fast on\|off] [--rtk 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\|--rtk\|--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 |
@@ -338,6 +340,7 @@ cdx history --summary --from 2026-05-01 --to 2026-05-28
 | `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 stats [name] [--since 7d\|today\|DATE] [--from DATE] [--to DATE] [--json]` | Aggregate launch counts, duration, and known headless token usage by session |
 | `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 |
@@ -369,6 +372,7 @@ Commands with machine-readable output:
 - `cdx context ... --json`
 - `cdx handoff ... --json`
 - `cdx history ... --json`
+- `cdx stats ... --json`
 - `cdx last --json`
 - `cdx doctor --json`
 - `cdx repair --json`
@@ -437,7 +441,14 @@ cdx run \
   --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.
+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.
+
+Known headless token usage is persisted in launch history and can be aggregated later:
+
+```bash
+cdx stats --since 7d --json
+cdx stats work
+```
 
 `cdx select` exposes the same session selection logic directly:
 

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/changelogs/CHANGELOGS_0_7_2.md

@@ -0,0 +1,41 @@
+# Changelog (`0.7.1 -> 0.7.2`)
+
+Release date: 2026-05-29
+
+## Update Reliability
+
+- Fixed Unix standalone update detection for installs under `~/.local/share/cdx-manager/<version>` so `cdx update` uses the standalone installer instead of incorrectly upgrading npm.
+- Added a post-update PATH verification check that runs the resolved `cdx -v` and warns when another older executable shadows the updated install.
+- Reduced the environment passed to the post-update version check so sensitive variables are not forwarded to the verification subprocess.
+- Aligned the PowerShell standalone installer with the Windows launcher by accepting `py`, `python`, or `python3`.
+
+## Headless Usage and Stats
+
+- Persisted normalized token usage from `cdx run --json` into launch history for future aggregation.
+- Added `cdx stats [name] [--since 7d|today|DATE] [--from DATE] [--to DATE] [--json]` to aggregate launches, successes, failures, duration, known usage runs, and token totals by session.
+- Continued extracting provider stdout usage even when a headless provider exits with an error, preserving useful usage data from structured failure payloads.
+
+## RTK Preference
+
+- Added `cdx set <session> --rtk on|off` and `cdx unset <session> --rtk` to store a per-session preference that encourages assistants to use RTK for noisy terminal commands.
+- Injected the RTK preference into interactive and headless launch prompts without rewriting commands automatically.
+- Added `cdx doctor` detection for the `rtk` CLI.
+
+## Coverage and Tests
+
+- Added focused coverage for update checking, context storage, RTK launch preferences, post-update shadow warnings, and per-session stats aggregation.
+- Fixed Windows CI portability in tests that exercise npm shim paths, version mismatch warnings, and context write byte counts.
+- Increased the Python test suite to 260 tests.
+
+## Release Metadata
+
+- Updated package metadata, CLI version output, README badge, pinned installer example, and release changelog to `v0.7.2`.
+
+## Validation and Regression Evidence
+
+- `npm run lint`
+- `npm test`
+- `npm pack --dry-run`
+- `node bin/cdx.js -v`
+- `python3 -m build`
+- `python3 -m twine check dist/*`

package/checksums/release-archives.json

@@ -28,6 +28,14 @@
     "v0.6.5": {
       "github_tarball_sha256": "f2280917ea75b5ae1e99a99b011f09704d89b1a7ae42497f5093e6fff9f814d9",
       "github_zip_sha256": "0b8491037310ed82cf44419d0de887bc0f768c6690c69153992fc4d5cda69676"
+    },
+    "v0.7.0": {
+      "github_tarball_sha256": "c80231884bf20c9ae74144a1ec16e0685c2fdac67d7d93a3c6219c5ac6fc14dd",
+      "github_zip_sha256": "0e6af29e59d3a93a07e07656d6c0c93803a674e65830ef33fa2322649b7139c2"
+    },
+    "v0.7.1": {
+      "github_tarball_sha256": "276cf2f094405bef674290ff8d1f2401f99afc10981c97efe4fe8293801715c8",
+      "github_zip_sha256": "5d5cdefec3ebcd61d4149b71895f4d5b79e604cf874b2d567910e578a8164670"
     }
   }
 }

package/install.ps1

@@ -12,14 +12,14 @@ if (-not $ChecksumsUrl) {
     $ChecksumsUrl = "https://raw.githubusercontent.com/$repo/main/checksums/release-archives.json"
 }
 
-function Require-Command {
+function Has-Command {
     param([string]$Name)
-    if (-not (Get-Command $Name -ErrorAction SilentlyContinue)) {
-        throw "cdx install: missing required command: $Name"
-    }
+    return [bool](Get-Command $Name -ErrorAction SilentlyContinue)
 }
 
-Require-Command python
+if (-not (Has-Command py) -and -not (Has-Command python) -and -not (Has-Command python3)) {
+    throw "cdx install: missing required command: py, python, or python3"
+}
 
 if (-not $Prefix) {
     $Prefix = Join-Path $env:LOCALAPPDATA "cdx-manager"

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "cdx-manager",
-  "version": "0.7.0",
+  "version": "0.7.2",
   "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.7.0"
+version = "0.7.2"
 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

@@ -30,6 +30,7 @@ from .cli_commands import (
     handle_rename,
     handle_run,
     handle_select,
+    handle_stats,
     handle_status,
     handle_set,
     handle_unset,
@@ -57,7 +58,7 @@ from .status_view import (
 )
 from .update_check import check_for_update
 
-VERSION = "0.7.0"
+VERSION = "0.7.2"
 
 
 # ---------------------------------------------------------------------------
@@ -79,9 +80,10 @@ def _print_help(use_color=False):
         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] [--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 set <name>|--sessions all|a,b|--provider PROVIDER [--power low|medium|high|xhigh|max] [--permission review|default|auto|full] [--fast on|off] [--rtk 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|--rtk|--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 stats [name] [--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)}",
         f"  {_style('cdx handoff <source> <target> [--json]', '36', use_color)}",
@@ -238,7 +240,7 @@ def main(argv, options=None):
         "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", "select", "run", "help", "version"
+            "add", "cp", "ren", "rename", "mv", "rmv", "clean", "doctor", "repair", "update", "ready", "notify", "context", "config", "set", "unset", "power", "perm", "fast", "model", "history", "stats", "handoff", "login", "logout", "disable", "enable", "export", "import", "select", "run", "help", "version"
         ) else None,
         "use_color": use_color,
     }
@@ -305,6 +307,9 @@ def main(argv, options=None):
     if command == "history":
         return handle_history(rest, ctx)
 
+    if command == "stats":
+        return handle_stats(rest, ctx)
+
     if command == "last":
         return handle_last(rest, ctx)
 

package/src/cli_commands.py

@@ -40,9 +40,10 @@ from .provider_runtime import (
 )
 from .repair import format_repair_report, repair_health
 from .backup_bundle import read_bundle_meta
+from .run_usage import empty_usage, extract_run_usage
 from .status_view import _format_status_detail, _format_status_rows
 from .update_check import LatestReleaseCheckError, fetch_latest_release, fetch_latest_release_or_raise, is_newer_version
-from .update_manager import build_update_plan, format_update_failure, run_update_plan
+from .update_manager import build_update_plan, format_update_failure, run_update_plan, verify_updated_command
 
 
 STATUS_USAGE = "Usage: cdx status [--json] [--refresh] | cdx status --small|-s [--refresh] | cdx status <name> [--json] [--refresh]"
@@ -53,11 +54,12 @@ EXPORT_USAGE = "Usage: cdx export <file> [--include-auth] [--force] [--json] [--
 IMPORT_USAGE = "Usage: cdx import <file> [--force] [--json] [--sessions name1,name2] [--passphrase-env VAR]"
 CONTEXT_USAGE = "Usage: cdx context show|path|init|edit|clear|set [text...] [--json]"
 HANDOFF_USAGE = "Usage: cdx handoff <name> [--json] | cdx handoff <source> <target> [--json]"
-SET_USAGE = "Usage: 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]"
-UNSET_USAGE = "Usage: cdx unset <name>|--sessions all|a,b|--provider PROVIDER (--power|--permission|--fast|--model|--priority|--all) [--json]"
+SET_USAGE = "Usage: cdx set <name>|--sessions all|a,b|--provider PROVIDER [--power low|medium|high|xhigh|max] [--permission review|default|auto|full] [--fast on|off] [--rtk on|off] [--model MODEL] [--priority 0..100] [--json]"
+UNSET_USAGE = "Usage: cdx unset <name>|--sessions all|a,b|--provider PROVIDER (--power|--permission|--fast|--rtk|--model|--priority|--all) [--json]"
 SETTING_ALIAS_USAGE = "Usage: cdx power|perm|fast|model <name|all|provider:PROVIDER|a,b> <value|default> [--json]"
 CONFIG_USAGE = "Usage: cdx config <name> [--json]"
 HISTORY_USAGE = "Usage: cdx history [name] [--limit N] [--summary] [--since 7d|today|DATE] [--from DATE] [--to DATE] [--json]"
+STATS_USAGE = "Usage: cdx stats [name] [--since 7d|today|DATE] [--from DATE] [--to DATE] [--json]"
 LAST_USAGE = "Usage: cdx last [--json]"
 SELECT_USAGE = "Usage: cdx select --provider PROVIDER [--min-reasoning-effort low|medium|high] [--min-power low|medium|high] [--require-ready] [--refresh] --json"
 RUN_USAGE = "Usage: 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"
@@ -503,6 +505,7 @@ def _parse_set_args(args):
         "--power": {"key": "power", "type": "str", "default": None},
         "--permission": {"key": "permission", "type": "str", "default": None},
         "--fast": {"key": "fast", "type": "str", "default": None, "transform": _parse_fast_value},
+        "--rtk": {"key": "rtk", "type": "str", "default": None, "transform": _parse_fast_value},
         "--model": {"key": "model", "type": "str", "default": None},
         "--priority": {"key": "priority", "type": "str", "default": None, "transform": _parse_priority_value},
         "--sessions": {"key": "sessions", "type": "str", "default": None, "transform": _parse_set_unset_sessions},
@@ -519,7 +522,7 @@ def _parse_set_args(args):
         raise CdxError(SET_USAGE)
     settings = {
         key: parsed[key]
-        for key in ("power", "permission", "fast", "model", "priority")
+        for key in ("power", "permission", "fast", "rtk", "model", "priority")
         if parsed[key] is not None
     }
     if not settings:
@@ -538,6 +541,7 @@ def _parse_unset_args(args):
         "--power": {"key": "power", "type": "bool", "default": False},
         "--permission": {"key": "permission", "type": "bool", "default": False},
         "--fast": {"key": "fast", "type": "bool", "default": False},
+        "--rtk": {"key": "rtk", "type": "bool", "default": False},
         "--model": {"key": "model", "type": "bool", "default": False},
         "--priority": {"key": "priority", "type": "bool", "default": False},
         "--all": {"key": "all", "type": "bool", "default": False},
@@ -553,8 +557,8 @@ def _parse_unset_args(args):
         raise CdxError(UNSET_USAGE)
     if not parsed["names"] and not parsed["sessions"] and not parsed["provider"]:
         raise CdxError(UNSET_USAGE)
-    keys = ["power", "permission", "fast", "model", "priority"] if parsed["all"] else [
-        key for key in ("power", "permission", "fast", "model", "priority") if parsed[key]
+    keys = ["power", "permission", "fast", "rtk", "model", "priority"] if parsed["all"] else [
+        key for key in ("power", "permission", "fast", "rtk", "model", "priority") if parsed[key]
     ]
     if not keys:
         raise CdxError(UNSET_USAGE)
@@ -817,6 +821,22 @@ def _parse_history_args(args, now=None):
     }
 
 
+def _parse_stats_args(args, now=None):
+    now = now or datetime.now().astimezone()
+    parsed = _parse_flag_args(args, {
+        "--since": {"key": "since", "type": "str", "default": None},
+        "--from": {"key": "from", "type": "str", "default": None},
+        "--to": {"key": "to", "type": "str", "default": None},
+        "--json": {"key": "json", "type": "bool", "default": False},
+    }, STATS_USAGE, positionals_key="names", max_positionals=1)
+    period = _parse_history_period(parsed, now)
+    return {
+        "name": parsed["names"][0] if parsed["names"] else None,
+        "period": period,
+        "json": parsed["json"],
+    }
+
+
 def _read_option_value(args, index, usage):
     if index + 1 >= len(args):
         raise CdxError(usage)
@@ -1201,15 +1221,6 @@ def _read_run_prompt(parsed):
         raise CdxError(f"Unable to read prompt file: {parsed['prompt_file']}") from error
 
 
-def _run_usage_payload():
-    return {
-        "input_tokens": None,
-        "output_tokens": None,
-        "reasoning_tokens": None,
-        "total_tokens": None,
-    }
-
-
 def _run_cdx_error_code(error):
     message = str(error)
     if message.startswith("Usage:"):
@@ -1233,10 +1244,16 @@ def _run_cdx_error_code(error):
 
 def _run_result_payload(ok, parsed, session, run_info=None, error=None, error_source=None, error_code=None):
     run_info = run_info or {}
+    usage = run_info.get("usage") if isinstance(run_info.get("usage"), dict) else (
+        extract_run_usage(session.get("provider"), run_info.get("stdout_path"))
+        if session else
+        empty_usage()
+    )
     return {
         "schema_version": API_SCHEMA_VERSION,
         "ok": bool(ok),
         "action": "run",
+        "launcher": "cdx",
         "session": session.get("name") if session else None,
         "provider": session.get("provider") if session else parsed.get("provider"),
         "model": parsed.get("model") or ((session.get("launch") or {}).get("model") if session else None),
@@ -1249,7 +1266,7 @@ def _run_result_payload(ok, parsed, session, run_info=None, error=None, error_so
         "transcript_path": run_info.get("transcript_path"),
         "stdout_path": run_info.get("stdout_path"),
         "stderr_path": run_info.get("stderr_path"),
-        "usage": _run_usage_payload(),
+        "usage": usage,
         "warnings": [],
         "error": None if ok else {
             "source": error_source or "cdx",
@@ -1283,6 +1300,7 @@ def handle_run(rest, ctx):
                     "run",
                     "no_suitable_session",
                     "No suitable session found.",
+                    launcher="cdx",
                     provider=parsed["provider"],
                 ))
                 return 1
@@ -1325,6 +1343,8 @@ def handle_run(rest, ctx):
             timeout_seconds=parsed.get("timeout_seconds"),
             spawn=ctx.get("spawn_headless") or ctx.get("spawn"),
         )
+        usage = extract_run_usage(run_session.get("provider"), run_info.get("stdout_path"))
+        run_info = {**run_info, "usage": usage}
         ok = run_info.get("returncode") == 0
         if ok:
             ctx["service"]["record_launch_history"](session["name"], {
@@ -1375,6 +1395,7 @@ def _format_launch_config(session):
         f"power:      {launch.get('power') or 'default'}",
         f"permission: {launch.get('permission') or 'default'}",
         f"fast:       {'on' if launch.get('fast') is True else 'off' if launch.get('fast') is False else 'default'}",
+        f"rtk:        {'on' if launch.get('rtk') is True else 'off' if launch.get('rtk') is False else 'default'}",
         f"model:      {launch.get('model') or 'default'}",
         f"priority:   {launch.get('priority') if launch.get('priority') is not None else 'default'}",
     ])
@@ -1544,6 +1565,79 @@ def _summarize_history(entries):
     )
 
 
+def _token_value(usage, key):
+    if not isinstance(usage, dict):
+        return None
+    value = usage.get(key)
+    try:
+        parsed = int(value)
+    except (TypeError, ValueError):
+        return None
+    return parsed if parsed >= 0 else None
+
+
+def _summarize_stats(entries):
+    rows = {}
+    for entry in entries:
+        name = entry.get("session_name") or "-"
+        row = rows.setdefault(name, {
+            "session_name": name,
+            "provider": entry.get("provider") or "-",
+            "launches": 0,
+            "successes": 0,
+            "failures": 0,
+            "duration_ms": 0,
+            "usage_runs": 0,
+            "input_tokens": 0,
+            "output_tokens": 0,
+            "reasoning_tokens": 0,
+            "total_tokens": 0,
+            "last_started_at": None,
+        })
+        row["launches"] += 1
+        if entry.get("status") == "success":
+            row["successes"] += 1
+        elif entry.get("status") == "failed":
+            row["failures"] += 1
+        try:
+            row["duration_ms"] += int(entry.get("duration_ms") or 0)
+        except (TypeError, ValueError):
+            pass
+        usage = entry.get("usage") if isinstance(entry.get("usage"), dict) else {}
+        parsed_usage = {
+            key: _token_value(usage, key)
+            for key in ("input_tokens", "output_tokens", "reasoning_tokens", "total_tokens")
+        }
+        if any(value is not None for value in parsed_usage.values()):
+            row["usage_runs"] += 1
+            for key, value in parsed_usage.items():
+                row[key] += value or 0
+        started = entry.get("started_at")
+        if started and (not row["last_started_at"] or started > row["last_started_at"]):
+            row["last_started_at"] = started
+            row["provider"] = entry.get("provider") or row["provider"]
+    return sorted(
+        rows.values(),
+        key=lambda item: (item["total_tokens"], item["duration_ms"], item.get("last_started_at") or "", item["session_name"]),
+        reverse=True,
+    )
+
+
+def _stats_totals(rows):
+    return {
+        "sessions": len(rows),
+        "launches": sum(row["launches"] for row in rows),
+        "successes": sum(row["successes"] for row in rows),
+        "failures": sum(row["failures"] for row in rows),
+        "duration_ms": sum(row["duration_ms"] for row in rows),
+        "usage_runs": sum(row["usage_runs"] for row in rows),
+        "input_tokens": sum(row["input_tokens"] for row in rows),
+        "output_tokens": sum(row["output_tokens"] for row in rows),
+        "reasoning_tokens": sum(row["reasoning_tokens"] for row in rows),
+        "total_tokens": sum(row["total_tokens"] for row in rows),
+    }
+
+
 def _format_history_period(period):
     if not _has_history_period(period or {}):
         return None
@@ -1611,6 +1705,55 @@ def _format_history(entries, use_color=False):
     ])
 
 
+def _format_token_count(value):
+    try:
+        amount = int(value)
+    except (TypeError, ValueError):
+        return "-"
+    if amount >= 1000000:
+        return f"{amount / 1000000:.1f}M"
+    if amount >= 1000:
+        return f"{amount / 1000:.1f}K"
+    return str(amount)
+
+
+def _format_stats(rows, totals, period=None, use_color=False):
+    from .cli_render import _format_relative_age, _pad_table
+
+    if not rows:
+        return "No launch stats for this period." if _has_history_period(period or {}) else "No launch stats."
+    table = [["SESSION", "PROV.", "RUNS", "USAGE", "IN", "OUT", "REASON", "TOTAL", "TIME", "LAST"]]
+    for row in rows:
+        table.append([
+            row["session_name"],
+            row["provider"],
+            str(row["launches"]),
+            str(row["usage_runs"]),
+            _format_token_count(row["input_tokens"]),
+            _format_token_count(row["output_tokens"]),
+            _format_token_count(row["reasoning_tokens"]),
+            _format_token_count(row["total_tokens"]),
+            _format_duration_ms(row["duration_ms"]),
+            _format_relative_age(row.get("last_started_at")),
+        ])
+    lines = ["Assistant stats:"]
+    period_line = _format_history_period(period or {})
+    if period_line:
+        lines.extend([period_line, ""])
+    lines.append(_pad_table(table))
+    lines.extend([
+        "",
+        _dim(
+            "Totals: "
+            f"{totals['launches']} runs, {totals['usage_runs']} with usage, "
+            f"{_format_token_count(totals['total_tokens'])} tokens, "
+            f"{_format_duration_ms(totals['duration_ms'])}.",
+            use_color,
+        ),
+    ])
+    return "\n".join(lines)
+
+
 def _apply_launch_settings(parsed, ctx, action="set"):
     targets = _resolve_bulk_launch_targets(parsed, ctx["service"])
     sessions = [
@@ -1723,6 +1866,32 @@ def handle_history(rest, ctx):
     return 0
 
 
+def handle_stats(rest, ctx):
+    now_fn = ctx["options"].get("now") or time.time
+    now = datetime.fromtimestamp(now_fn()).astimezone()
+    parsed = _parse_stats_args(rest, now=now)
+    entries = ctx["service"]["get_launch_history"](parsed["name"], limit=0)
+    entries = _filter_history_period(entries, parsed["period"])
+    rows = _summarize_stats(entries)
+    totals = _stats_totals(rows)
+    message = (
+        f"Calculated stats for {parsed['name']}"
+        if parsed["name"]
+        else "Calculated stats"
+    )
+    if parsed["json"]:
+        _write_json(ctx, _json_success(
+            "stats",
+            message,
+            period=_public_history_period(parsed["period"]),
+            stats=rows,
+            totals=totals,
+        ))
+        return 0
+    ctx["out"](f"{_format_stats(rows, totals, period=parsed['period'], use_color=ctx['use_color'])}\n")
+    return 0
+
+
 def _resolve_last_launch_session(ctx):
     for entry in ctx["service"]["get_launch_history"](limit=0):
         name = entry.get("session_name")
@@ -2353,11 +2522,21 @@ def handle_update(rest, ctx):
     if failed:
         raise CdxError(format_update_failure(results))
 
+    warnings = []
+    version_warning = verify_updated_command(
+        target_version,
+        runner=ctx["options"].get("runVersionCheck"),
+        env=ctx.get("env"),
+    )
+    if version_warning:
+        warnings.append(version_warning)
+
     message = f"Updated cdx-manager to {target_version}"
     if json_flag:
         _write_json(ctx, _json_success(
             "update",
             message,
+            warnings=warnings,
             updated=True,
             current_version=current_version,
             target_version=target_version,
@@ -2366,6 +2545,8 @@ def handle_update(rest, ctx):
         ))
         return 0
     ctx["out"](f"{_success(message, ctx['use_color'])}\n")
+    for warning in warnings:
+        ctx["out"](f"{_warn(warning['message'], ctx['use_color'])}\n")
     return 0
 
 

package/src/cli_render.py

@@ -75,10 +75,12 @@ def _style_pct(value, use_color=False):
     text = _format_pct(value)
     if value is None:
         return _style(text, "2", use_color)
-    if value == 0:
+    if value <= 0:
         return _style(text, "31", use_color)
     if value <= 10:
         return _style(text, "33", use_color)
+    if value > 80:
+        return _style(text, "96", use_color)
     return _style(text, "32", use_color)
 
 

package/src/health.py

@@ -39,6 +39,14 @@ def collect_health_report(service, base_dir, env=None):
         status = "OK" if path else "WARN"
         issues.append(_issue(status, f"{command}_cli", f"{command} CLI {'found' if path else 'not found'}", path))
 
+    rtk_path = shutil.which("rtk", path=env.get("PATH"))
+    issues.append(_issue(
+        "OK" if rtk_path else "WARN",
+        "rtk_cli",
+        "RTK CLI found" if rtk_path else "RTK CLI not found; assistants can still run normally but may use more context on noisy commands",
+        rtk_path,
+    ))
+
     script_bin = env.get("CDX_SCRIPT_BIN", "script")
     script_path = shutil.which(script_bin, path=env.get("PATH"))
     issues.append(_issue(

package/src/provider_runtime.py

@@ -15,6 +15,10 @@ from .errors import CdxError
 
 LOG_ROTATE_BYTES = 10 * 1024 * 1024  # 10 MB
 REASONING_EFFORT_VALUES = {"low", "medium", "high"}
+RTK_PROMPT = (
+    "When running noisy shell commands, prefer RTK wrappers (`rtk <command>`) if `rtk` is available. "
+    "Use raw commands when exact, unfiltered output is required."
+)
 LAUNCH_PERMISSION_ARGS = {
     PROVIDER_CLAUDE: {
         "review": ["--permission-mode", "plan"],
@@ -29,6 +33,12 @@ LAUNCH_PERMISSION_ARGS = {
         "full": ["-s", "danger-full-access", "-a", "never"],
     },
 }
+HEADLESS_CODEX_PERMISSION_ARGS = {
+    "review": ["-s", "read-only"],
+    "default": ["-s", "workspace-write"],
+    "auto": ["-s", "workspace-write", "-c", 'approval_policy="never"'],
+    "full": ["--dangerously-bypass-approvals-and-sandbox"],
+}
 
 
 def _home_env_overrides(auth_home):
@@ -278,12 +288,21 @@ def _default_script_args(transcript_path, spec):
     return ["-q", "-F", transcript_path, spec["command"]] + spec["args"]
 
 
+def _rtk_enabled(session):
+    return (session.get("launch") or {}).get("rtk") is True
+
+
+def _with_launch_preferences(session, initial_prompt=None):
+    if not _rtk_enabled(session):
+        return initial_prompt
+    if initial_prompt:
+        return f"{RTK_PROMPT}\n\n{initial_prompt}"
+    return RTK_PROMPT
+
+
 def _build_launch_spec(session, cwd=None, env_override=None, initial_prompt=None, capture_transcript=True):
-    if initial_prompt is not None:
-        if not isinstance(initial_prompt, str):
-            raise CdxError("initial_prompt must be a string.")
-        if len(initial_prompt) > 32768:
-            raise CdxError("initial_prompt exceeds maximum allowed length.")
+    initial_prompt = _with_launch_preferences(session, initial_prompt)
+    _validate_initial_prompt(initial_prompt)
     cwd = cwd or os.getcwd()
     env_override = env_override or {}
     env = {**os.environ, **env_override}
@@ -347,6 +366,69 @@ def _build_launch_spec(session, cwd=None, env_override=None, initial_prompt=None
     }, capture_transcript=capture_transcript, env=env)
 
 
+def _validate_initial_prompt(initial_prompt):
+    if initial_prompt is not None:
+        if not isinstance(initial_prompt, str):
+            raise CdxError("initial_prompt must be a string.")
+        if len(initial_prompt) > 32768:
+            raise CdxError("initial_prompt exceeds maximum allowed length.")
+
+
+def _build_headless_launch_spec(session, cwd=None, env_override=None, initial_prompt=None):
+    initial_prompt = _with_launch_preferences(session, initial_prompt)
+    _validate_initial_prompt(initial_prompt)
+    cwd = cwd or os.getcwd()
+    env = {**os.environ, **(env_override or {})}
+    launch = session.get("launch") or {}
+    power = _launch_power(session)
+    permission = launch.get("permission")
+    model = launch.get("model")
+
+    if session["provider"] == PROVIDER_CLAUDE:
+        args = ["--print", "--output-format", "json", "--name", session["name"]]
+        if model:
+            args += ["--model", model]
+        args += _launch_config_args(session)
+        if initial_prompt:
+            args.append(initial_prompt)
+        auth_home = _get_auth_home(session)
+        claude_env = _claude_env(env, auth_home)
+        oauth_token = _read_anthropic_oauth_token(auth_home)
+        if oauth_token:
+            claude_env["CLAUDE_CODE_OAUTH_TOKEN"] = oauth_token
+        return {
+            "command": "claude",
+            "args": args,
+            "options": {"cwd": cwd, "env": claude_env},
+            "label": "claude",
+        }
+
+    if session["provider"] == PROVIDER_CODEX:
+        args = ["exec", "--json", "-C", cwd]
+        if model:
+            args += ["-m", model]
+        if power:
+            args += ["-c", f'model_reasoning_effort="{power}"']
+        if permission:
+            args += HEADLESS_CODEX_PERMISSION_ARGS.get(permission, [])
+        if initial_prompt:
+            args.append(initial_prompt)
+        return {
+            "command": "codex",
+            "args": args,
+            "options": {"cwd": cwd, "env": {**env, "CODEX_HOME": _get_auth_home(session)}},
+            "label": "codex",
+        }
+
+    return _build_launch_spec(
+        session,
+        cwd=cwd,
+        env_override=env_override,
+        initial_prompt=initial_prompt,
+        capture_transcript=False,
+    )
+
+
 def _headless_artifact_paths(session, run_id=None):
     run_id = run_id or uuid.uuid4().hex
     log_dir = _get_launch_transcript_dir(session)
@@ -397,12 +479,11 @@ def _headless_run_info(paths, spec, start_time, returncode):
 def _run_headless_provider_command(session, cwd=None, env_override=None, initial_prompt=None,
                                    timeout_seconds=None, spawn=None, run_id=None):
     spawn = spawn or subprocess.Popen
-    spec = _build_launch_spec(
+    spec = _build_headless_launch_spec(
         session,
         cwd=cwd,
         env_override=env_override,
         initial_prompt=initial_prompt,
-        capture_transcript=False,
     )
     paths = _headless_artifact_paths(session, run_id=run_id)
     start_time = datetime.now(timezone.utc)

package/src/run_usage.py

@@ -0,0 +1,133 @@
+import json
+
+
+USAGE_KEYS = ("input_tokens", "output_tokens", "reasoning_tokens", "total_tokens")
+SUPPORTED_PROVIDERS = {"claude", "codex"}
+
+
+def empty_usage():
+    return {key: None for key in USAGE_KEYS}
+
+
+def extract_run_usage(provider, stdout_path):
+    if not stdout_path or not provider:
+        return empty_usage()
+    if provider not in SUPPORTED_PROVIDERS:
+        return empty_usage()
+    try:
+        with open(stdout_path, "r", encoding="utf-8", errors="replace") as handle:
+            text = handle.read()
+    except OSError:
+        return empty_usage()
+    if not text.strip():
+        return empty_usage()
+
+    records = _parse_json_records(text)
+    if not records:
+        return empty_usage()
+
+    usage = _extract_usage_from_records(records)
+    if not _has_usage(usage):
+        return empty_usage()
+    return usage
+
+
+def _parse_json_records(text):
+    stripped = text.strip()
+    try:
+        return [json.loads(stripped)]
+    except json.JSONDecodeError:
+        pass
+
+    records = []
+    for line in stripped.splitlines():
+        line = line.strip()
+        if not line:
+            continue
+        try:
+            records.append(json.loads(line))
+        except json.JSONDecodeError:
+            return []
+    return records
+
+
+def _extract_usage_from_records(records):
+    latest = None
+    for record in records:
+        candidate = _find_usage(record)
+        if _has_usage(candidate):
+            latest = candidate
+    return latest or empty_usage()
+
+
+def _find_usage(value):
+    if isinstance(value, dict):
+        direct = _usage_from_dict(value)
+        if _has_usage(direct):
+            return direct
+        for child in value.values():
+            found = _find_usage(child)
+            if _has_usage(found):
+                return found
+    if isinstance(value, list):
+        for child in value:
+            found = _find_usage(child)
+            if _has_usage(found):
+                return found
+    return empty_usage()
+
+
+def _usage_from_dict(value):
+    usage = value.get("usage") if isinstance(value.get("usage"), dict) else value
+    if not isinstance(usage, dict):
+        return empty_usage()
+
+    input_tokens = _int_value(
+        usage.get("input_tokens"),
+        usage.get("prompt_tokens"),
+        usage.get("cache_creation_input_tokens"),
+        usage.get("cache_read_input_tokens"),
+    )
+    output_tokens = _int_value(usage.get("output_tokens"), usage.get("completion_tokens"))
+    reasoning_tokens = _int_value(
+        usage.get("reasoning_tokens"),
+        _nested_int(usage, "output_tokens_details", "reasoning_tokens"),
+        _nested_int(usage, "completion_tokens_details", "reasoning_tokens"),
+    )
+    total_tokens = _first_int(usage.get("total_tokens"))
+    if total_tokens is None and input_tokens is not None and output_tokens is not None:
+        total_tokens = input_tokens + output_tokens
+
+    return {
+        "input_tokens": input_tokens,
+        "output_tokens": output_tokens,
+        "reasoning_tokens": reasoning_tokens,
+        "total_tokens": total_tokens,
+    }
+
+
+def _nested_int(value, parent, child):
+    nested = value.get(parent)
+    if not isinstance(nested, dict):
+        return None
+    return nested.get(child)
+
+
+def _first_int(value):
+    try:
+        parsed = int(value)
+    except (TypeError, ValueError):
+        return None
+    return parsed if parsed >= 0 else None
+
+
+def _int_value(*values):
+    parsed = [_first_int(value) for value in values]
+    parsed = [value for value in parsed if value is not None]
+    if not parsed:
+        return None
+    return sum(parsed)
+
+
+def _has_usage(usage):
+    return isinstance(usage, dict) and any(usage.get(key) is not None for key in USAGE_KEYS)

package/src/session_service.py

@@ -123,6 +123,18 @@ def _normalize_launch_settings(settings):
                 normalized["fast"] = False
             else:
                 raise CdxError(f"Unsupported fast value: {settings['fast']}")
+    if "rtk" in settings and settings["rtk"] is not None:
+        value = settings["rtk"]
+        if isinstance(value, bool):
+            normalized["rtk"] = value
+        else:
+            text = str(value).strip().lower()
+            if text in ("on", "true", "1", "yes"):
+                normalized["rtk"] = True
+            elif text in ("off", "false", "0", "no"):
+                normalized["rtk"] = False
+            else:
+                raise CdxError(f"Unsupported rtk value: {settings['rtk']}")
     if "model" in settings and settings["model"] is not None:
         model = str(settings["model"]).strip()
         if not model:
@@ -189,14 +201,23 @@ def _to_local_iso(value):
     return parsed.astimezone().isoformat()
 
 
+def _normalize_pct_value(value):
+    if value is None:
+        return None
+    try:
+        return max(0, min(100, round(float(value))))
+    except (TypeError, ValueError):
+        return None
+
+
 def _normalize_status_payload(payload=None):
     if payload is None:
         payload = {}
     now = _local_now_iso()
     return {
-        "usage_pct": payload.get("usage_pct"),
-        "remaining_5h_pct": payload.get("remaining_5h_pct"),
-        "remaining_week_pct": payload.get("remaining_week_pct"),
+        "usage_pct": _normalize_pct_value(payload.get("usage_pct")),
+        "remaining_5h_pct": _normalize_pct_value(payload.get("remaining_5h_pct")),
+        "remaining_week_pct": _normalize_pct_value(payload.get("remaining_week_pct")),
         "credits": payload.get("credits"),
         "reset_5h_at": payload.get("reset_5h_at"),
         "reset_week_at": payload.get("reset_week_at"),
@@ -297,8 +318,8 @@ def _compute_available_pct(status):
     if not status:
         return None
     values = [
-        status.get("remaining_5h_pct"),
-        status.get("remaining_week_pct"),
+        _normalize_pct_value(status.get("remaining_5h_pct")),
+        _normalize_pct_value(status.get("remaining_week_pct")),
     ]
     values = [value for value in values if value is not None]
     if not values:
@@ -791,7 +812,7 @@ def create_session_service(options=None):
             raise CdxError(f"Unknown session: {name}")
         if not keys:
             raise CdxError("At least one launch setting is required.")
-        allowed = {"power", "permission", "fast", "model", "priority"}
+        allowed = {"power", "permission", "fast", "rtk", "model", "priority"}
         unknown = [key for key in keys if key not in allowed]
         if unknown:
             raise CdxError(f"Unsupported launch setting: {', '.join(unknown)}")
@@ -981,8 +1002,8 @@ def create_session_service(options=None):
                 "status": "enabled" if enabled else "disabled",
                 "auth_status": (s.get("auth") or {}).get("status") or "unknown",
                 "auth_checked_at": _to_local_iso((s.get("auth") or {}).get("lastCheckedAt")),
-                "remaining_5h_pct": row_status.get("remaining_5h_pct") if row_status else None,
-                "remaining_week_pct": row_status.get("remaining_week_pct") if row_status else None,
+                "remaining_5h_pct": _normalize_pct_value(row_status.get("remaining_5h_pct")) if row_status else None,
+                "remaining_week_pct": _normalize_pct_value(row_status.get("remaining_week_pct")) if row_status else None,
                 "credits": row_status.get("credits") if row_status else None,
                 "available_pct": _compute_available_pct(row_status),
                 "reset_5h_at": row_status.get("reset_5h_at") if row_status else None,

package/src/update_manager.py

@@ -1,4 +1,6 @@
 import os
+import re
+import shutil
 import subprocess
 import sys
 from pathlib import Path
@@ -22,7 +24,14 @@ def _normalize_version(value):
 
 
 def _is_standalone_install(package_root):
-    return package_root.parent.name == "versions"
+    if package_root.parent.name == "versions":
+        return True
+    return (
+        package_root.parent.name == "cdx-manager"
+        and re.match(r"^\d+\.\d+\.\d+(?:[-+][0-9A-Za-z.-]+)?$", package_root.name) is not None
+        and (package_root / "install.sh").exists()
+        and (package_root / "bin" / "cdx").exists()
+    )
 
 
 def _is_source_checkout(package_root):
@@ -200,6 +209,76 @@ def run_update_plan(plan, runner=None, env=None):
     return results
 
 
+def _version_check_env(env):
+    source = env or os.environ
+    allowed = {
+        key: source[key]
+        for key in ("PATH", "PATHEXT", "SystemRoot", "COMSPEC", "WINDIR")
+        if source.get(key)
+    }
+    return allowed
+
+
+def verify_updated_command(target_version, runner=None, env=None):
+    target = _normalize_version(target_version)
+    if not target:
+        return None
+    env = env or os.environ
+    executable = shutil.which("cdx", path=env.get("PATH"))
+    if not executable:
+        return {
+            "code": "update_version_check_failed",
+            "message": "Updated cdx-manager, but no cdx executable was found on PATH.",
+            "target_version": target,
+            "resolved_version": None,
+            "path": None,
+        }
+    runner = runner or subprocess.run
+    try:
+        result = runner(
+            [executable, "-v"],
+            cwd=None,
+            env=_version_check_env(env),
+            check=False,
+            capture_output=True,
+            text=True,
+        )
+    except OSError as error:
+        return {
+            "code": "update_version_check_failed",
+            "message": f"Updated cdx-manager, but failed to verify {executable}: {error}",
+            "target_version": target,
+            "resolved_version": None,
+            "path": executable,
+        }
+
+    version = str(_result_text(result, "stdout") or "").strip().splitlines()
+    version = _normalize_version(version[0]) if version else None
+    code = _result_code(result)
+    if code not in (0, None) or not version:
+        message = str(_result_text(result, "stderr") or _result_text(result, "stdout") or "").strip()
+        suffix = f": {message}" if message else "."
+        return {
+            "code": "update_version_check_failed",
+            "message": f"Updated cdx-manager, but failed to verify {executable}{suffix}",
+            "target_version": target,
+            "resolved_version": version,
+            "path": executable,
+        }
+    if version != target:
+        return {
+            "code": "update_version_mismatch",
+            "message": (
+                f"Updated cdx-manager to {target}, but PATH resolves {executable} "
+                f"which reports {version}."
+            ),
+            "target_version": target,
+            "resolved_version": version,
+            "path": executable,
+        }
+    return None
+
+
 def format_update_failure(results):
     if not results:
         return "Update failed."