cdx-manager 0.7.1 → 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.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.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.1 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`
@@ -439,6 +443,13 @@ cdx run \
 
 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:
 
 ```bash

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

@@ -32,6 +32,10 @@
     "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.1",
+  "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.1"
+version = "0.7.2"
 description = "Terminal session manager for Codex and Claude accounts."
 readme = "README.md"
 requires-python = ">=3.9"

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.1"
+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

@@ -43,7 +43,7 @@ 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]"
@@ -54,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"
@@ -504,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},
@@ -520,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:
@@ -539,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},
@@ -554,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)
@@ -818,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)
@@ -1225,9 +1244,9 @@ 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 = (
+    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 ok and session else
+        if session else
         empty_usage()
     )
     return {
@@ -1324,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"], {
@@ -1374,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'}",
     ])
@@ -1543,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
@@ -1610,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 = [
@@ -1722,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")
@@ -2352,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,
@@ -2365,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/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"],
@@ -284,7 +288,20 @@ 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):
+    initial_prompt = _with_launch_preferences(session, initial_prompt)
     _validate_initial_prompt(initial_prompt)
     cwd = cwd or os.getcwd()
     env_override = env_override or {}
@@ -358,6 +375,7 @@ def _validate_initial_prompt(initial_prompt):
 
 
 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 {})}

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:
@@ -800,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)}")

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."