cdx-manager 0.4.2 → 0.4.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.4.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.4.4-4C8BF5) ![Python](https://img.shields.io/badge/python-3.9%2B-3776AB?logo=python&logoColor=white)
 
 **Run multiple Codex and Claude sessions from one terminal. Switch between accounts instantly.**
 
@@ -122,7 +122,7 @@ For a specific version:
 
 ```bash
 curl -fsSL https://raw.githubusercontent.com/AlexAgo83/cdx-manager/main/install.sh -o install.sh
-CDX_VERSION=v0.4.2 sh install.sh
+CDX_VERSION=v0.4.4 sh install.sh
 ```
 
 From source:
@@ -143,6 +143,12 @@ npm install -g .
 
 `cdx` is now available globally. Changes to the source take effect immediately — no reinstall needed.
 
+To update an installed copy later:
+
+```bash
+cdx update
+```
+
 To uninstall:
 
 ```bash
@@ -242,6 +248,7 @@ cdx status
 | `cdx import <file> [--sessions a,b] [--passphrase-env VAR] [--force] [--json]` | Import sessions from a bundle into the current `CDX_HOME` |
 | `cdx doctor [--json]` | Inspect CLI dependencies, CDX_HOME permissions, missing state, orphan profiles, and pending quarantines |
 | `cdx repair [--dry-run] [--force] [--json]` | Plan or apply safe repairs for missing state files, quarantines, and orphan profiles |
+| `cdx update [--check] [--yes] [--json] [--version TAG]` | Update cdx-manager using the installer that matches how it was installed |
 | `cdx notify <name> --at-reset [--poll seconds] [--once] [--json]` | Wait for a session reset time and send a desktop notification when due |
 | `cdx notify --next-ready [--poll seconds] [--once] [--json]` | Wait until the recommended session is usable or needs a refresh after reset |
 | `cdx status [--json] [--refresh]` | Show token usage table for all sessions; JSON returns a versioned payload with structured warnings |
@@ -272,6 +279,7 @@ Commands with machine-readable output:
 - `cdx logout ... --json`
 - `cdx doctor --json`
 - `cdx repair --json`
+- `cdx update --json`
 - `cdx notify ... --json`
 
 Success payloads follow a shared envelope:

package/changelogs/CHANGELOGS_0_1_1.md

@@ -1,14 +1,14 @@
-# CHANGELOGS_0_1_1
+# Changelog (`0.1.0 -> 0.1.1`)
 
 Release date: 2026-04-16
 
-## CDX Manager 0.1.1
+## Major Highlights
+- CDX Manager 0.1.1 is the first packaged release of the multi-provider terminal session manager for Codex and Claude accounts.
+- It turns the initial Logics-scoped idea into a usable CLI: isolated per-session auth homes, interactive provider launch, status extraction from local artifacts, Claude usage refresh through Anthropic rate-limit headers, log capture, cleanup commands, and release-ready package metadata.
 
-CDX Manager 0.1.1 is the first packaged release of the multi-provider terminal session manager for Codex and Claude accounts.
+## Generated Commit Summary
 
-It turns the initial Logics-scoped idea into a usable CLI: isolated per-session auth homes, interactive provider launch, status extraction from local artifacts, Claude usage refresh through Anthropic rate-limit headers, log capture, cleanup commands, and release-ready package metadata.
-
-### At a glance
+## At a glance
 
 - Added the `cdx` CLI entrypoint with conventional `--help`, `--version`, session listing, creation, launch, copy, removal, login, logout, clean, and status commands
 - Added persistent session storage under `CDX_HOME`, with URL-encoded session names and per-session rehydration state
@@ -22,7 +22,7 @@ It turns the initial Logics-scoped idea into a usable CLI: isolated per-session
 - Migrated the implementation to Python while keeping npm-based install and validation scripts
 - Added root packaging metadata, MIT license, README, contribution guidance, and release notes
 
-### Session management
+## Session management
 
 - `cdx add <name>` creates Codex sessions by default.
 - `cdx add claude <name>` creates Claude sessions with a dedicated `claude-home`.
@@ -31,7 +31,7 @@ It turns the initial Logics-scoped idea into a usable CLI: isolated per-session
 - `cdx rmv <name> [--force]` removes the session registry entry and its auth directory.
 - Session state is stored in a versioned JSON registry and per-session state files under `CDX_HOME`.
 
-### Authentication and launch flow
+## Authentication and launch flow
 
 - Codex sessions use `codex login status`, `codex login`, and `codex logout`.
 - Claude sessions use `claude auth status`, `claude auth login`, and `claude auth logout`.
@@ -39,7 +39,7 @@ It turns the initial Logics-scoped idea into a usable CLI: isolated per-session
 - Signals from the wrapper process are forwarded to the child provider process.
 - Codex launches show a reminder to run `/status` inside Codex when usage data needs refreshing.
 
-### Usage and status reporting
+## Usage and status reporting
 
 - `cdx status` renders an aligned table for all sessions.
 - `cdx status <name>` renders a detailed view for one session.
@@ -48,7 +48,7 @@ It turns the initial Logics-scoped idea into a usable CLI: isolated per-session
 - Available percentage is computed from the stricter remaining quota window.
 - Cached statuses are enriched from newer or more detailed local artifacts when available.
 
-### Codex status extraction
+## Codex status extraction
 
 - Parses Codex `/status` blocks from logs and JSONL history.
 - Handles ANSI / terminal control sequences and narrow terminal layouts.
@@ -56,7 +56,7 @@ It turns the initial Logics-scoped idea into a usable CLI: isolated per-session
 - Uses account identity in Codex status blocks to avoid accepting pasted status output from another account.
 - Prefers direct launch logs over noisier conversational rollout JSONL artifacts.
 
-### Claude status extraction
+## Claude status extraction
 
 - Parses `Current session` and `Current week` blocks from Claude transcripts.
 - Extracts 5-hour reset values from `Current session`, including AM/PM formats such as `Resets at 5:00 AM`.
@@ -64,26 +64,26 @@ It turns the initial Logics-scoped idea into a usable CLI: isolated per-session
 - Keeps Claude 5-hour and weekly reset values separate in status output.
 - Refreshes Claude usage automatically from Anthropic rate-limit headers when credentials are available.
 
-### Local time behavior
+## Local time behavior
 
 - Claude API reset timestamps are formatted in the machine's local timezone.
 - Log-derived time-only reset values are inferred in the local timezone.
 - Status `updated_at` values from API, JSONL, and file metadata are normalized to local ISO timestamps.
 
-### Logging and cleanup
+## Logging and cleanup
 
 - Provider launches are captured to local transcript logs via `script`.
 - Launch logs include unique timestamped filenames to avoid overwriting active or recent transcripts.
 - Logs are rotated around the 10 MB threshold.
 - `cdx clean [name]` clears launch transcript logs for one session or all sessions.
 
-### Packaging
+## Packaging
 
 - Published package version is `0.1.1`.
 - The npm tarball is restricted to the CLI entrypoint, source package, README, license, and release changelogs.
 - Local project-only files such as `.claude`, Logics workflow docs, and tests are excluded from the package tarball.
 
-### Validation
+## Validation and Regression Evidence
 
 ```bash
 npm run lint
@@ -92,7 +92,7 @@ python3 bin/cdx --version
 npm --cache /tmp/cdx-npm-cache pack --dry-run
 ```
 
-### Notes
+## Notes
 
 - This is the first release changelog, so it summarizes the full history from the initial Logics bootstrap through the 0.1.1 release preparation.
 - The package remains marked `private` in `package.json`; publication requires intentionally changing that release policy.

package/changelogs/CHANGELOGS_0_2_0.md

@@ -1,12 +1,13 @@
-# CHANGELOGS_0_2_0
+# Changelog (`0.1.1 -> 0.2.0`)
 
 Release date: 2026-04-16
 
-## CDX Manager 0.2.0
+## Major Highlights
+- CDX Manager 0.2.0 focuses on operational reliability. It adds health checks, safe repair workflows, reset notifications, stronger session-store behavior, and clearer status output for choosing the best account.
 
-CDX Manager 0.2.0 focuses on operational reliability. It adds health checks, safe repair workflows, reset notifications, stronger session-store behavior, and clearer status output for choosing the best account.
+## Generated Commit Summary
 
-### At a glance
+## At a glance
 
 - Added `cdx doctor` to inspect local CLI dependencies, `CDX_HOME` writability, missing session state, orphan profiles, and pending quarantines.
 - Added `cdx repair` with dry-run-by-default behavior and `--force` for safe repairs.
@@ -18,7 +19,7 @@ CDX Manager 0.2.0 focuses on operational reliability. It adds health checks, saf
 - Decorated CLI output with terminal-native color support while respecting `NO_COLOR`, `CLICOLOR`, and TTY behavior.
 - Split the CLI implementation into smaller modules for status rendering, provider runtime, commands, and storage.
 
-### Doctor and repair
+## Doctor and repair
 
 - `cdx doctor [--json]` reports installation and data-layout health.
 - `cdx repair [--dry-run] [--force] [--json]` plans repairs by default.
@@ -26,14 +27,14 @@ CDX Manager 0.2.0 focuses on operational reliability. It adds health checks, saf
 - Pending quarantine profile directories can be cleaned up.
 - Orphan profiles are moved to quarantine with `--force` instead of being deleted directly.
 
-### Notifications
+## Notifications
 
 - `cdx notify <name> --at-reset` waits for the selected session reset time.
 - `cdx notify --next-ready` waits for the recommended session to become usable or due for refresh.
 - `--poll seconds`, `--once`, and `--json` are supported.
 - macOS desktop notifications are sent through `osascript` when available, with terminal output as the consistent fallback.
 
-### Status improvements
+## Status improvements
 
 - `cdx status` now includes a direct priority line before the usage tip.
 - The priority line prefers immediately usable accounts, accounts with earlier relevant resets, and accounts without credit fallback when appropriate.
@@ -41,7 +42,7 @@ CDX Manager 0.2.0 focuses on operational reliability. It adds health checks, saf
 - The main `cdx` session list now formats updated timestamps as relative ages.
 - JSON status output keeps a stable shape even when live Claude refresh fails; refresh warnings are written to stderr.
 
-### Reliability and safety
+## Reliability and safety
 
 - Session names now reject reserved command names including `doctor`, `repair`, and `notify`.
 - Session removal uses a quarantine flow and surfaces cleanup failures instead of silently ignoring them.
@@ -51,7 +52,7 @@ CDX Manager 0.2.0 focuses on operational reliability. It adds health checks, saf
 - Codex launch falls back without transcript capture when the `script` wrapper is unavailable or fails before producing a transcript.
 - Signal interruptions no longer trigger transcript fallback relaunches.
 
-### Validation
+## Validation and Regression Evidence
 
 ```bash
 npm run lint
@@ -62,7 +63,7 @@ npm test
 ./bin/cdx --version
 ```
 
-### Notes
+## Notes
 
 - The package remains marked `private` in `package.json`; npm publication still requires an explicit policy change.
 - No Git remote is configured in the current local repository, so this release is prepared locally and tagged locally only.

package/changelogs/CHANGELOGS_0_2_1.md

@@ -1,12 +1,13 @@
-# CHANGELOGS_0_2_1
+# Changelog (`0.2.0 -> 0.2.1`)
 
 Release date: 2026-04-16
 
-## CDX Manager 0.2.1
+## Major Highlights
+- CDX Manager 0.2.1 prepares the package for npm publication.
 
-CDX Manager 0.2.1 prepares the package for npm publication.
+## Generated Commit Summary
 
-### Packaging
+## Packaging
 
 - Removed the private package flag so npm publication is possible.
 - Added npm package metadata: license, author, repository, bugs, homepage, keywords, and Node engine declaration.
@@ -14,7 +15,7 @@ CDX Manager 0.2.1 prepares the package for npm publication.
 - Normalized the `bin.cdx` path with `npm pkg fix`.
 - Documented the future npm install command in the README.
 
-### Validation
+## Validation and Regression Evidence
 
 ```bash
 npm run lint
@@ -23,7 +24,7 @@ npm --cache /tmp/cdx-npm-cache publish --dry-run
 npm view cdx-manager name version --registry https://registry.npmjs.org/
 ```
 
-### Notes
+## Notes
 
 - `npm view cdx-manager` currently returns `E404`, so the package name appears available on the npm registry.
 - This release is prepared for npm publication but has not been published yet.

package/changelogs/CHANGELOGS_0_3_0.md

@@ -1,12 +1,13 @@
-# CHANGELOGS_0_3_0
+# Changelog (`0.2.1 -> 0.3.0`)
 
 Release date: 2026-04-16
 
-## CDX Manager 0.3.0
+## Major Highlights
+- CDX Manager 0.3.0 adds Python-native and standalone installation paths in addition to npm.
 
-CDX Manager 0.3.0 adds Python-native and standalone installation paths in addition to npm.
+## Generated Commit Summary
 
-### Packaging
+## Packaging
 
 - Added `pyproject.toml` so the CLI can be installed with `pipx`, `pip`, or `uv tool`.
 - Added the Python console entrypoint `cdx = "src.cli:cli_entry"`.
@@ -15,7 +16,7 @@ CDX Manager 0.3.0 adds Python-native and standalone installation paths in additi
 - Documented npm, pipx, uv, curl installer, and source installation paths.
 - Added GitHub Actions automation for PyPI publication when a GitHub Release is published.
 
-### Validation
+## Validation and Regression Evidence
 
 ```bash
 npm run lint
@@ -26,7 +27,7 @@ python3 -m venv /tmp/cdx-pyinstall
 npm --cache /tmp/cdx-npm-cache publish --dry-run
 ```
 
-### Notes
+## Notes
 
 - PyPI publication is now technically possible, but still requires PyPI credentials and an explicit publish step.
 - The standalone installer defaults to the latest GitHub Release and supports `CDX_VERSION=vX.Y.Z` for pinned installs.

package/changelogs/CHANGELOGS_0_3_1.md

@@ -1,18 +1,19 @@
-# CHANGELOGS_0_3_1
+# Changelog (`0.3.0 -> 0.3.1`)
 
 Release date: 2026-04-16
 
-## CDX Manager 0.3.1
+## Major Highlights
+- CDX Manager 0.3.1 is a release-channel synchronization update.
 
-CDX Manager 0.3.1 is a release-channel synchronization update.
+## Generated Commit Summary
 
-### Packaging
+## Packaging
 
 - Uses npm Trusted Publishing through GitHub Actions OIDC instead of long-lived npm tokens.
 - Keeps npm, PyPI, GitHub Releases, pipx, uv, and the standalone installer aligned on the same release version.
 - Retains the Python-native packaging and standalone install support introduced in 0.3.0.
 
-### Validation
+## Validation and Regression Evidence
 
 ```bash
 npm run lint
@@ -22,6 +23,6 @@ python -m build
 python -m twine check dist/*
 ```
 
-### Notes
+## Notes
 
 - This release exists because the npm Trusted Publishing workflow was added after the `v0.3.0` tag. A fresh release is required for GitHub Actions to run the updated workflow definition for npm publishing.

package/changelogs/CHANGELOGS_0_3_2.md

@@ -1,18 +1,19 @@
-# CHANGELOGS_0_3_2
+# Changelog (`0.3.1 -> 0.3.2`)
 
 Release date: 2026-04-16
 
-## CDX Manager 0.3.2
+## Major Highlights
+- CDX Manager 0.3.2 updates the npm release workflow to use the npm CLI version required for Trusted Publishing.
 
-CDX Manager 0.3.2 updates the npm release workflow to use the npm CLI version required for Trusted Publishing.
+## Generated Commit Summary
 
-### Packaging
+## Packaging
 
 - Runs the npm publish workflow on Node 24.
 - Installs npm 11 before publishing so GitHub Actions OIDC trusted publishing is supported.
 - Keeps npm, PyPI, GitHub Releases, pipx, uv, and the standalone installer aligned on the same release version.
 
-### Validation
+## Validation and Regression Evidence
 
 ```bash
 npm run lint

package/changelogs/CHANGELOGS_0_3_3.md

@@ -1,12 +1,13 @@
-# CHANGELOGS_0_3_3
+# Changelog (`0.3.2 -> 0.3.3`)
 
 Release date: 2026-04-16
 
-## CDX Manager 0.3.3
+## Major Highlights
+- CDX Manager 0.3.3 adds Windows compatibility across the full codebase.
 
-CDX Manager 0.3.3 adds Windows compatibility across the full codebase.
+## Generated Commit Summary
 
-### Windows support
+## Windows support
 
 - **Session store locking**: replaced `fcntl.flock` (Unix-only) with `msvcrt.locking` on Windows, with `seek(0)` to ensure consistent byte-range locking.
 - **Signal handling**: guarded `signal.SIGHUP` references behind `hasattr` checks — `SIGHUP` does not exist on Windows.
@@ -15,11 +16,11 @@ CDX Manager 0.3.3 adds Windows compatibility across the full codebase.
 - **ANSI colors**: `cli_entry` enables VT processing via `ctypes.windll.kernel32.SetConsoleMode` on Windows so color output works in terminals that support it.
 - **Console encoding**: `cli_entry` reconfigures `stdout`/`stderr` to UTF-8 on Windows to prevent `UnicodeEncodeError` on non-ASCII session names.
 
-### Maintenance
+## Maintenance
 
 - Expanded `.gitignore` with standard Python build artifacts (`__pycache__/`, `*.egg-info/`, `dist/`, `build/`), virtual environments, coverage output, and OS-specific files (`.DS_Store`, `Thumbs.db`, `desktop.ini`).
 
-### Validation
+## Validation and Regression Evidence
 
 ```bash
 npm run lint

package/changelogs/CHANGELOGS_0_3_4.md

@@ -1,12 +1,13 @@
-# CHANGELOGS_0_3_4
+# Changelog (`0.3.3 -> 0.3.4`)
 
 Release date: 2026-04-16
 
-## CDX Manager 0.3.4
+## Major Highlights
+- CDX Manager 0.3.4 makes the CLI consumable by other applications through a structured JSON contract and rounds out the Windows release surface.
 
-CDX Manager 0.3.4 makes the CLI consumable by other applications through a structured JSON contract and rounds out the Windows release surface.
+## Generated Commit Summary
 
-### JSON CLI API
+## JSON CLI API
 
 - Added `cdx --json` to list known sessions as a machine-readable payload.
 - Added `--json` support for session-management commands: `add`, `cp`, `ren`, `rmv`, `clean`, `login`, and `logout`.
@@ -14,14 +15,14 @@ CDX Manager 0.3.4 makes the CLI consumable by other applications through a struc
 - Added a shared stderr error envelope for JSON mode with machine-readable `code`, `message`, and `exit_code`.
 - Documented the JSON contract in the README so editor plugins and desktop apps can integrate without scraping human-readable terminal output.
 
-### Windows release hardening
+## Windows release hardening
 
 - Added a native `install.ps1` installer for Windows.
 - Documented supported Windows install paths and the optional transcript-capture fallback.
 - Added targeted `win32` unit coverage for CLI startup, provider environment isolation, notifications, and session-store locking.
 - Added a Windows CI smoke flow that installs the package and exercises core CLI commands with shimmed providers.
 
-### Validation
+## Validation and Regression Evidence
 
 ```bash
 npm run lint

package/changelogs/CHANGELOGS_0_4_0.md

@@ -1,12 +1,13 @@
-# CHANGELOGS_0_4_0
+# Changelog (`0.3.4 -> 0.4.0`)
 
 Release date: 2026-04-16
 
-## CDX Manager 0.4.0
+## Major Highlights
+- CDX Manager 0.4.0 adds portable session backup and restore, surfaces cached release-update notices inside the CLI, and tightens Codex status isolation across multiple accounts.
 
-CDX Manager 0.4.0 adds portable session backup and restore, surfaces cached release-update notices inside the CLI, and tightens Codex status isolation across multiple accounts.
+## Generated Commit Summary
 
-### Portable session bundles
+## Portable session bundles
 
 - Added `cdx export <file>` and `cdx import <file>` for moving sessions between machines.
 - Added optional encrypted auth export with `--include-auth` and interactive or environment-driven passphrase handling.
@@ -14,20 +15,20 @@ CDX Manager 0.4.0 adds portable session backup and restore, surfaces cached rele
 - Preserved per-session state alongside session records so imported environments keep their local metadata.
 - Added bundle schema validation and integrity checks during import.
 
-### Update awareness and installer hardening
+## Update awareness and installer hardening
 
 - Added cached GitHub release checks so the CLI can warn when a newer `cdx-manager` release is available without hitting the network on every command.
 - Surfaced update notices in interactive output and structured JSON warnings.
 - Hardened the standalone install scripts to consume official release-archive checksums when available.
 - Documented the checksum-backed installer flow and backup/restore usage in the README.
 
-### Status isolation fix
+## Status isolation fix
 
 - Fixed Codex status parsing so boxed blank lines in TUI transcripts no longer drop the `Account:` context line.
 - Restored account-aware status selection when multiple sessions contain similar `/status` blocks.
 - Added regression coverage for mixed-account transcript selection and bundle export/import flows.
 
-### Validation
+## Validation and Regression Evidence
 
 ```bash
 npm run lint

package/changelogs/CHANGELOGS_0_4_1.md

@@ -1,25 +1,26 @@
-# CHANGELOGS_0_4_1
+# Changelog (`0.4.0 -> 0.4.1`)
 
 Release date: 2026-04-19
 
-## CDX Manager 0.4.1
+## Major Highlights
+- CDX Manager 0.4.1 fixes the Windows npm entry point so `cdx` no longer depends on `python3.exe` being present on PATH. It now ships a Node launcher that resolves a usable Python 3 interpreter cross-platform before invoking the existing Python CLI entry point.
 
-CDX Manager 0.4.1 fixes the Windows npm entry point so `cdx` no longer depends on `python3.exe` being present on PATH. It now ships a Node launcher that resolves a usable Python 3 interpreter cross-platform before invoking the existing Python CLI entry point.
+## Generated Commit Summary
 
-### Windows npm launcher
+## Windows npm launcher
 
 - Replaced the npm-facing `bin.cdx` target with a Node launcher at `bin/cdx.js`.
 - Added Python discovery that tries `py -3`, then `python`, then `python3` on Windows.
 - Kept the existing Python script under `bin/cdx` as the primary CLI entry point.
 - Added a clear error message when no compatible Python 3 interpreter is available.
 
-### Documentation and packaging
+## Documentation and packaging
 
 - Updated the README with Windows Python prerequisites and the new launcher behavior.
 - Added a shared portable Node wrapper for the npm test and lint scripts.
 - Bumped the package versions for the npm and PyPI release workflows.
 
-### Validation
+## Validation and Regression Evidence
 
 ```bash
 npm run lint

package/changelogs/CHANGELOGS_0_4_2.md

@@ -1,28 +1,29 @@
-# CHANGELOGS_0_4_2
+# Changelog (`0.4.1 -> 0.4.2`)
 
 Release date: 2026-04-19
 
-## CDX Manager 0.4.2
+## Major Highlights
+- CDX Manager 0.4.2 fixes Codex session bootstrap on Windows so `cdx add` can reuse an existing logged-in Codex CLI without requiring a second manual login flow. It also hardens executable resolution for the Codex probe so Windows shell shims and direct process spawning behave consistently.
 
-CDX Manager 0.4.2 fixes Codex session bootstrap on Windows so `cdx add` can reuse an existing logged-in Codex CLI without requiring a second manual login flow. It also hardens executable resolution for the Codex probe so Windows shell shims and direct process spawning behave consistently.
+## Generated Commit Summary
 
-### Codex auth bootstrap
+## Codex auth bootstrap
 
 - Seeded new Codex session auth homes from the global `~/.codex/auth.json` when available.
 - Short-circuited the Codex auth probe when a session already has an auth file in its isolated home.
 - Kept the per-session auth directory model intact after bootstrap so session isolation still applies.
 
-### Windows command resolution
+## Windows command resolution
 
 - Resolved `codex` through the active `PATH` before invoking the login-status probe.
 - Applied the same command-resolution path to interactive provider launches when the default process spawner is used.
 - Added regression coverage for Codex auth bootstrap and resolved-command spawning on Windows.
 
-### Documentation
+## Documentation
 
 - Documented the Codex auth bootstrap behavior in the README.
 
-### Validation
+## Validation and Regression Evidence
 
 ```bash
 npm run lint

package/changelogs/CHANGELOGS_0_4_3.md

@@ -0,0 +1,36 @@
+# Changelog (`0.4.2 -> 0.4.3`)
+
+Release date: 2026-04-19
+
+## Major Highlights
+
+- Generated from 1 code commit between `v0.4.2` and `HEAD` on 2026-04-19.
+- Touched areas: Windows Codex status discovery, status formatting, and regression coverage.
+- `cdx status` now reads Codex's structured Windows `rate_limits` payloads instead of falling back to `n/a`.
+- Reset dates now render in the same short format as the rest of the UI, so the table stays readable.
+- When a session profile has no usable Codex status artifact, `cdx` can fall back to the global Codex home on Windows.
+
+## Generated Commit Summary
+
+## Codex Status on Windows
+
+- Added support for structured `rate_limits` data emitted by Codex's JSONL session history.
+- Kept support for the older transcript-style status blocks, so existing artifacts still resolve.
+- Narrowed the global-home fallback to real `cdx` runs on the default home, which avoids cross-contaminating temporary test homes.
+
+## Status Formatting
+
+- Normalized structured reset timestamps to the short `Apr 25 18:52` style used elsewhere in `cdx status`.
+- Preserved the existing relative labels such as `in 3h 57m` in the rendered table.
+
+## Validation and Regression Coverage
+
+- Added a regression test for structured Codex rollout rate limits.
+- Kept the existing session-service and CLI validation suite green.
+
+## Validation and Regression Evidence
+
+- `python -m unittest discover -s test -p "test_session_service_py.py"`
+- `python -m unittest discover -s test -p "test_cli_py.py"`
+- `python -m unittest discover -s test -p "test_runtime_py.py"`
+- `node bin/cdx.js status`

package/changelogs/CHANGELOGS_0_4_4.md

@@ -0,0 +1,33 @@
+# Changelog (`0.4.3 -> 0.4.4`)
+
+Release date: 2026-04-20
+
+## Major Highlights
+
+- Generated from the release work on `cdx update`, the first built-in self-update path for `cdx-manager`.
+- Added a version-aware update command that can check for a newer release, confirm interactively, and delegate to the right installer for the current installation type.
+- Kept the existing update warning behavior intact so the CLI still surfaces newer releases on startup.
+- Reserved `update` as a session name to avoid collisions with the new command.
+
+## `cdx update`
+
+- Added `cdx update --check` for a quick release check without applying changes.
+- Added `cdx update --yes` for non-interactive environments.
+- Added `cdx update --version TAG` so maintainers can target a specific release.
+- Routed standalone installs through `install.sh` / `install.ps1`.
+- Routed npm installs through `npm install -g cdx-manager@...`.
+- Routed Python environment installs through `python -m pip install --upgrade ...`.
+- Routed source checkouts through `git pull --ff-only` or an explicit tag checkout when a version is requested.
+- Refused source updates when the checkout contains uncommitted changes.
+
+## Validation and Regression Coverage
+
+- Added CLI coverage for update checks, update execution, and version-aware help text.
+- Added session-service coverage for the new reserved command name.
+- Added unit coverage for installation detection and source-checkout safety in the update planner.
+- Kept the existing CLI and session-service test suites green.
+
+## Validation and Regression Evidence
+
+- `python3 -m unittest test.test_cli_py test.test_session_service_py test.test_update_manager_py`
+- `npm run lint`

package/package.json

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

package/src/cli.py

@@ -21,6 +21,7 @@ from .cli_commands import (
     handle_repair,
     handle_rename,
     handle_status,
+    handle_update,
 )
 from .cli_render import (
     _format_sessions,
@@ -44,7 +45,7 @@ from .status_view import (
 )
 from .update_check import check_for_update
 
-VERSION = "0.4.2"
+VERSION = "0.4.4"
 
 
 # ---------------------------------------------------------------------------
@@ -72,6 +73,7 @@ def _print_help(use_color=False):
         f"  {_style('cdx import <file> [--sessions a,b] [--passphrase-env VAR] [--force] [--json]', '36', use_color)}",
         f"  {_style('cdx doctor [--json]', '36', use_color)}",
         f"  {_style('cdx repair [--dry-run] [--force] [--json]', '36', use_color)}",
+        f"  {_style('cdx update [--check] [--yes] [--json] [--version TAG]', '36', use_color)}",
         f"  {_style('cdx notify <name> --at-reset [--json]', '36', use_color)}",
         f"  {_style('cdx notify --next-ready [--json]', '36', use_color)}",
         f"  {_style('cdx <name> [--json]', '36', use_color)}",
@@ -205,8 +207,9 @@ def main(argv, options=None):
         "spawn": spawn,
         "spawn_sync": spawn_sync,
         "stdin_is_tty": stdin_is_tty,
+        "version": VERSION,
         "update_notice": _get_update_notice(service, env, options) if command not in (
-            "add", "cp", "ren", "rename", "mv", "rmv", "clean", "doctor", "repair", "notify", "status", "login", "logout", "export", "import", "help", "version"
+            "add", "cp", "ren", "rename", "mv", "rmv", "clean", "doctor", "repair", "update", "notify", "status", "login", "logout", "export", "import", "help", "version"
         ) else None,
         "use_color": use_color,
     }
@@ -238,6 +241,9 @@ def main(argv, options=None):
     if command == "repair":
         return handle_repair(rest, ctx)
 
+    if command == "update":
+        return handle_update(rest, ctx)
+
     if command == "notify":
         return handle_notify(rest, ctx)
 

package/src/cli_commands.py

@@ -22,11 +22,14 @@ from .provider_runtime import (
 from .repair import format_repair_report, repair_health
 from .backup_bundle import read_bundle_meta
 from .status_view import _format_status_detail, _format_status_rows
+from .update_check import fetch_latest_release, is_newer_version
+from .update_manager import build_update_plan, format_update_failure, run_update_plan
 
 
 STATUS_USAGE = "Usage: cdx status [--json] [--refresh] | cdx status --small|-s [--refresh] | cdx status <name> [--json] [--refresh]"
 DOCTOR_USAGE = "Usage: cdx doctor [--json]"
 REPAIR_USAGE = "Usage: cdx repair [--dry-run] [--force] [--json]"
+UPDATE_USAGE = "Usage: cdx update [--check] [--yes] [--json] [--version TAG]"
 EXPORT_USAGE = "Usage: cdx export <file> [--include-auth] [--force] [--json] [--sessions name1,name2] [--passphrase-env VAR]"
 IMPORT_USAGE = "Usage: cdx import <file> [--force] [--json] [--sessions name1,name2] [--passphrase-env VAR]"
 API_SCHEMA_VERSION = 1
@@ -102,6 +105,45 @@ def _parse_session_names(value):
     return names
 
 
+def _parse_update_args(args):
+    parsed = {
+        "check": False,
+        "json": False,
+        "yes": False,
+        "version": None,
+    }
+    index = 0
+    while index < len(args):
+        arg = args[index]
+        if arg == "--check":
+            parsed["check"] = True
+            index += 1
+            continue
+        if arg == "--json":
+            parsed["json"] = True
+            index += 1
+            continue
+        if arg == "--yes":
+            parsed["yes"] = True
+            index += 1
+            continue
+        if arg == "--version":
+            value, index = _read_option_value(args, index, UPDATE_USAGE)
+            parsed["version"] = value
+            continue
+        if arg.startswith("--version="):
+            parsed["version"] = arg.split("=", 1)[1]
+            index += 1
+            continue
+        raise CdxError(UPDATE_USAGE)
+
+    if parsed["check"] and parsed["version"]:
+        raise CdxError("Usage: cdx update --check cannot be combined with --version.")
+    if parsed["version"] is not None and not parsed["version"].strip():
+        raise CdxError("Usage: cdx update [--check] [--yes] [--json] [--version TAG]")
+    return parsed
+
+
 def _parse_export_args(args):
     parsed = {
         "file_path": None,
@@ -649,6 +691,91 @@ def handle_logout(rest, ctx):
     return 0
 
 
+def handle_update(rest, ctx):
+    parsed = _parse_update_args(rest)
+    json_flag = parsed["json"]
+    current_version = str(ctx.get("version") or "").strip()
+    release_fetcher = ctx["options"].get("fetchLatestRelease") or fetch_latest_release
+    target_version = None
+    release_url = None
+    update_available = False
+
+    if parsed["version"] is not None:
+        target_version = str(parsed["version"]).strip().lstrip("v")
+    else:
+        latest = release_fetcher()
+        if not latest:
+            raise CdxError("Unable to check for the latest cdx-manager release. Check your network and try again.")
+        target_version = str(latest.get("latest_version") or "").strip()
+        release_url = latest.get("url")
+        if not target_version:
+            raise CdxError("Unable to determine the latest cdx-manager release.")
+        update_available = is_newer_version(current_version, target_version)
+        if parsed["check"] or not update_available:
+            message = (
+                f"Update available: cdx-manager {target_version} (current {current_version})"
+                if update_available
+                else f"cdx-manager {current_version} is already up to date."
+            )
+            if json_flag:
+                _write_json(ctx, _json_success(
+                    "update",
+                    message,
+                    checked=True,
+                    update_available=update_available,
+                    current_version=current_version,
+                    target_version=target_version,
+                    release_url=release_url,
+                    warnings=[{
+                        "code": "update_available",
+                        "message": message,
+                        "latest_version": target_version,
+                        "url": release_url,
+                    }] if update_available else [],
+                ))
+                return 0
+            ctx["out"](f"{_warn(message, ctx['use_color']) if update_available else _success(message, ctx['use_color'])}\n")
+            return 0
+
+    if not parsed["yes"]:
+        if not ctx["stdin_is_tty"]:
+            raise CdxError("Update requires an interactive terminal or --yes in non-interactive mode.")
+        answer = input(f"Update cdx-manager to {target_version}? [y/N] ")
+        if answer.strip().lower() not in ("y", "yes"):
+            message = "Cancelled."
+            if json_flag:
+                _write_json(ctx, _json_success("update", message, cancelled=True, current_version=current_version, target_version=target_version))
+                return 0
+            ctx["out"](f"{_warn(message, ctx['use_color'])}\n")
+            return 0
+
+    plan = build_update_plan(
+        target_version=target_version,
+        package_root=ctx["options"].get("packageRoot"),
+        prefix=ctx["options"].get("prefix"),
+        base_prefix=ctx["options"].get("basePrefix"),
+    )
+    results = run_update_plan(plan, runner=ctx["options"].get("runUpdate"), env=ctx.get("env"))
+    failed = any((result.get("returncode") not in (0, None)) for result in results)
+    if failed:
+        raise CdxError(format_update_failure(results))
+
+    message = f"Updated cdx-manager to {target_version}"
+    if json_flag:
+        _write_json(ctx, _json_success(
+            "update",
+            message,
+            updated=True,
+            current_version=current_version,
+            target_version=target_version,
+            mode=plan["mode"],
+            steps=results,
+        ))
+        return 0
+    ctx["out"](f"{_success(message, ctx['use_color'])}\n")
+    return 0
+
+
 def handle_launch(command, ctx):
     json_flag = "--json" in ctx["options"].get("raw_args", [])
     update_notice = ctx.get("update_notice")

package/src/session_service.py

@@ -33,6 +33,7 @@ RESERVED_SESSION_NAMES = {
     "rename",
     "rmv",
     "status",
+    "update",
     "version",
     "--help",
     "-h",
@@ -540,6 +541,18 @@ def create_session_service(options=None):
             session["provider"],
             expected_account_email=expected_account_email,
         )
+        if (
+            session["provider"] == "codex"
+            and not artifact
+            and os.path.abspath(base_dir) == os.path.abspath(get_cdx_home(env))
+        ):
+            global_root = _get_global_codex_home(env)
+            if global_root and os.path.abspath(global_root) != os.path.abspath(source_root):
+                artifact = find_latest_status_artifact(
+                    global_root,
+                    session["provider"],
+                    expected_account_email=expected_account_email,
+                )
         if not artifact:
             if _is_low_confidence_status_source(current_status):
                 return None

package/src/status_source.py

@@ -47,6 +47,89 @@ def _safe_stat(file_path):
         return None
 
 
+def _format_local_reset_timestamp(value):
+    if value is None or value == "":
+        return None
+    try:
+        timestamp = float(value)
+    except (TypeError, ValueError):
+        return None
+    if timestamp > 1_000_000_000_000:
+        timestamp /= 1000.0
+    try:
+        dt = datetime.fromtimestamp(timestamp, tz=timezone.utc).astimezone()
+    except (OverflowError, OSError, ValueError):
+        return None
+    return f"{MONTH_ABBR[dt.month - 1]} {dt.day} {dt.strftime('%H:%M')}"
+
+
+def _normalize_timestamp_value(value):
+    return _format_local_reset_timestamp(value)
+
+
+def _coerce_percentage(value):
+    if value is None or value == "":
+        return None
+    try:
+        return max(0, min(100, int(float(value))))
+    except (TypeError, ValueError):
+        return None
+
+
+def _extract_structured_rate_limits(record):
+    if not isinstance(record, dict):
+        return None
+
+    rate_limits = record.get("rate_limits")
+    if not isinstance(rate_limits, dict):
+        return None
+
+    primary = rate_limits.get("primary") or {}
+    secondary = rate_limits.get("secondary") or {}
+    credits = rate_limits.get("credits") or {}
+
+    primary_used = _coerce_percentage(primary.get("used_percent"))
+    secondary_used = _coerce_percentage(secondary.get("used_percent"))
+    remaining_5h_pct = None if primary_used is None else max(0, 100 - primary_used)
+    remaining_week_pct = None if secondary_used is None else max(0, 100 - secondary_used)
+
+    result = {
+        "usage_pct": primary_used if primary_used is not None else secondary_used,
+        "remaining_5h_pct": remaining_5h_pct,
+        "remaining_week_pct": remaining_week_pct,
+        "credits": None,
+        "reset_5h_at": _normalize_timestamp_value(primary.get("resets_at")),
+        "reset_week_at": _normalize_timestamp_value(secondary.get("resets_at")),
+        "reset_at": None,
+        "raw_status_text": json.dumps(rate_limits, sort_keys=True),
+    }
+
+    balance = credits.get("balance")
+    if balance not in (None, ""):
+        result["credits"] = str(balance).strip()
+
+    result["reset_at"] = result["reset_week_at"] or result["reset_5h_at"]
+    if result["usage_pct"] is None and result["remaining_5h_pct"] is None and result["remaining_week_pct"] is None:
+        return None
+    return result
+
+
+def _collect_structured_rate_limit_statuses(value, output=None):
+    if output is None:
+        output = []
+    if isinstance(value, dict):
+        structured = _extract_structured_rate_limits(value)
+        if structured:
+            output.append(structured)
+        else:
+            for item in value.values():
+                _collect_structured_rate_limit_statuses(item, output)
+    elif isinstance(value, list):
+        for item in value:
+            _collect_structured_rate_limit_statuses(item, output)
+    return output
+
+
 def _collect_text_values(value, output=None):
     if output is None:
         output = []
@@ -162,6 +245,13 @@ def _extract_jsonl_texts(file_path, provider=None):
             continue
         try:
             record = json.loads(line)
+            for structured in _collect_structured_rate_limit_statuses(record):
+                items.append({
+                    "source_ref": f"{file_path}:{line_index + 1}",
+                    "timestamp": record.get("timestamp"),
+                    "text": structured["raw_status_text"],
+                    "structured": structured,
+                })
             payload_texts = _collect_text_values(record.get("payload") or {})
             for candidate in payload_texts:
                 if isinstance(candidate, str) and candidate.strip():
@@ -523,9 +613,6 @@ def find_latest_status_artifact(root_dir, provider=None, expected_account_email=
     )
     records = []
     for fp in candidates:
-        normalized_fp = fp.replace(os.sep, "/")
-        if "/sessions/" in normalized_fp and os.path.basename(fp).startswith("rollout"):
-            continue
         if fp.endswith(".jsonl"):
             records.extend(_extract_jsonl_texts(fp, provider))
         elif fp.endswith(".log"):
@@ -538,6 +625,17 @@ def find_latest_status_artifact(root_dir, provider=None, expected_account_email=
         ):
             continue
         parsed = extract_named_statuses_from_text(candidate["text"])
+        if not parsed and candidate.get("structured"):
+            parsed = {
+                "usage_pct": candidate["structured"].get("usage_pct"),
+                "remaining_5h_pct": candidate["structured"].get("remaining_5h_pct"),
+                "remaining_week_pct": candidate["structured"].get("remaining_week_pct"),
+                "credits": candidate["structured"].get("credits"),
+                "reset_5h_at": candidate["structured"].get("reset_5h_at"),
+                "reset_week_at": candidate["structured"].get("reset_week_at"),
+                "reset_at": candidate["structured"].get("reset_at"),
+                "raw_status_text": candidate["structured"].get("raw_status_text"),
+            }
         if not parsed:
             continue
         ts = candidate.get("timestamp")

package/src/update_check.py

@@ -28,6 +28,10 @@ def _is_newer_version(current_version, latest_version):
     return latest > current
 
 
+def is_newer_version(current_version, latest_version):
+    return _is_newer_version(current_version, latest_version)
+
+
 def _cache_path(base_dir):
     return os.path.join(base_dir, "state", "update-check.json")
 
@@ -63,6 +67,13 @@ def _fetch_latest_release():
     }
 
 
+def fetch_latest_release():
+    try:
+        return _fetch_latest_release()
+    except (urllib.error.URLError, TimeoutError, ValueError, OSError):
+        return None
+
+
 def check_for_update(base_dir, current_version, env=None, now_fn=None):
     env = env or os.environ
     now_fn = now_fn or (lambda: datetime.now(timezone.utc).timestamp())
@@ -83,9 +94,8 @@ def check_for_update(base_dir, current_version, env=None, now_fn=None):
             }
         return None
 
-    try:
-        latest = _fetch_latest_release()
-    except (urllib.error.URLError, TimeoutError, ValueError, OSError):
+    latest = fetch_latest_release()
+    if not latest:
         return None
 
     payload = {

package/src/update_manager.py

@@ -0,0 +1,208 @@
+import os
+import subprocess
+import sys
+from pathlib import Path
+
+from .errors import CdxError
+
+
+def _package_root(path=None):
+    if path is not None:
+        return Path(path).resolve()
+    return Path(__file__).resolve().parents[1]
+
+
+def _normalize_version(value):
+    if value is None:
+        return None
+    text = str(value).strip()
+    if not text:
+        return None
+    return text.lstrip("v")
+
+
+def _is_standalone_install(package_root):
+    return package_root.parent.name == "versions"
+
+
+def _is_source_checkout(package_root):
+    return (package_root / ".git").exists()
+
+
+def _is_git_dirty(package_root):
+    try:
+        result = subprocess.run(
+            ["git", "-C", str(package_root), "status", "--porcelain"],
+            capture_output=True,
+            text=True,
+            check=False,
+        )
+    except FileNotFoundError as error:
+        raise CdxError("git is required to update a source checkout.") from error
+    return bool((result.stdout or "").strip())
+
+
+def _is_python_env(prefix=None, base_prefix=None):
+    prefix = prefix or sys.prefix
+    base_prefix = base_prefix or sys.base_prefix
+    return prefix != base_prefix
+
+
+def detect_installation(package_root=None, prefix=None, base_prefix=None):
+    root = _package_root(package_root)
+    if _is_standalone_install(root):
+        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)}
+    return {"mode": "unknown", "package_root": str(root)}
+
+
+def _join_command(*parts):
+    return [str(part) for part in parts if part is not None]
+
+
+def _build_standalone_step(package_root, target_version):
+    package_root = _package_root(package_root)
+    env = {}
+    if target_version:
+        env["CDX_VERSION"] = target_version
+    if sys.platform == "win32":
+        return {
+            "label": "standalone installer",
+            "command": _join_command("powershell", "-ExecutionPolicy", "Bypass", "-File", package_root / "install.ps1"),
+            "cwd": str(package_root),
+            "env": env,
+        }
+    return {
+        "label": "standalone installer",
+        "command": _join_command("sh", package_root / "install.sh"),
+        "cwd": str(package_root),
+        "env": env,
+    }
+
+
+def _build_source_steps(package_root, target_version):
+    package_root = _package_root(package_root)
+    if _is_git_dirty(package_root):
+        raise CdxError(
+            "Your source checkout has uncommitted changes. "
+            "Commit or stash them before running cdx update."
+        )
+    if target_version:
+        return [
+            {
+                "label": "fetch tags",
+                "command": _join_command("git", "-C", package_root, "fetch", "--tags", "--force"),
+                "cwd": str(package_root),
+                "env": {},
+            },
+            {
+                "label": f"checkout v{target_version}",
+                "command": _join_command("git", "-C", package_root, "checkout", f"v{target_version}"),
+                "cwd": str(package_root),
+                "env": {},
+            },
+        ]
+    return [
+        {
+            "label": "git pull --ff-only",
+            "command": _join_command("git", "-C", package_root, "pull", "--ff-only"),
+            "cwd": str(package_root),
+            "env": {},
+        }
+    ]
+
+
+def _build_python_step(target_version):
+    command = [sys.executable, "-m", "pip", "install", "--upgrade"]
+    if target_version:
+        command.append(f"cdx-manager=={target_version}")
+    else:
+        command.append("cdx-manager")
+    return {
+        "label": "python package upgrade",
+        "command": command,
+        "cwd": None,
+        "env": {},
+    }
+
+
+def _build_npm_step(target_version):
+    spec = f"cdx-manager@{target_version}" if target_version else "cdx-manager@latest"
+    return {
+        "label": "npm global upgrade",
+        "command": ["npm", "install", "-g", spec],
+        "cwd": None,
+        "env": {},
+    }
+
+
+def build_update_plan(target_version=None, package_root=None, env=None, prefix=None, base_prefix=None):
+    root = _package_root(package_root)
+    version = _normalize_version(target_version)
+    detection = detect_installation(root, prefix=prefix, base_prefix=base_prefix)
+    mode = detection["mode"]
+    if mode == "standalone":
+        steps = [_build_standalone_step(root, version)]
+    elif mode == "source":
+        steps = _build_source_steps(root, version)
+    elif mode == "python":
+        steps = [_build_python_step(version)]
+    elif mode == "npm":
+        steps = [_build_npm_step(version)]
+    else:
+        raise CdxError(
+            "Unable to determine how cdx-manager was installed. "
+            "Set CDX_UPDATE_METHOD or update it manually."
+        )
+    return {
+        "mode": mode,
+        "package_root": str(root),
+        "target_version": version,
+        "steps": steps,
+    }
+
+
+def _result_code(result):
+    if isinstance(result, dict):
+        return result.get("returncode") if result.get("returncode") is not None else result.get("status")
+    return getattr(result, "returncode", getattr(result, "status", None))
+
+
+def _result_text(result, attr):
+    if isinstance(result, dict):
+        return result.get(attr)
+    return getattr(result, attr, "")
+
+
+def run_update_plan(plan, runner=None, env=None):
+    runner = runner or subprocess.run
+    results = []
+    for step in plan["steps"]:
+        step_env = {**(env or os.environ), **(step.get("env") or {})}
+        kwargs = {"cwd": step.get("cwd"), "env": step_env, "check": False}
+        result = runner(step["command"], **kwargs)
+        code = _result_code(result)
+        results.append({
+            "label": step["label"],
+            "command": step["command"],
+            "cwd": step.get("cwd"),
+            "returncode": code,
+            "stdout": _result_text(result, "stdout"),
+            "stderr": _result_text(result, "stderr"),
+        })
+        if code not in (0, None):
+            break
+    return results
+
+
+def format_update_failure(results):
+    if not results:
+        return "Update failed."
+    last = results[-1]
+    message = last.get("stderr") or last.get("stdout") or "Update failed."
+    return f"{last['label']} failed: {str(message).strip()}"