cdx-manager 0.18.3 → 0.18.4

package/README.md

@@ -1,6 +1,10 @@
+<img src="docs/assets/icon.png" alt="CDX Manager icon" width="64" align="left" />
+
 # CDX Manager
 
-[![License](https://img.shields.io/badge/license-MIT-4C8BF5)](LICENSE) ![Version](https://img.shields.io/badge/version-v0.18.3-4C8BF5) ![Python](https://img.shields.io/badge/python-3.9%2B-3776AB?logo=python&logoColor=white)
+<br clear="left"/>
+
+[![License](https://img.shields.io/badge/license-MIT-4C8BF5)](LICENSE) ![Version](https://img.shields.io/badge/version-v0.18.4-4C8BF5) ![Python](https://img.shields.io/badge/python-3.9%2B-3776AB?logo=python&logoColor=white)
 
 **Stop guessing which AI account still has quota.** `cdx` tracks the rate-limit window of every Codex and Claude account you own, tells you which one is usable right now, and launches it with isolated auth — in one command.
 
@@ -515,8 +519,9 @@ cdx history --summary --from 2026-05-01 --to 2026-05-28
 | `cdx status <name> [--json] [--refresh\|--cached] [--timeout SECONDS]` | Show detailed usage breakdown for one session; `--cached` avoids live provider refreshes |
 | `cdx tray status [--json] [--refresh]` | Emit the tray snapshot: one icon state, one line per enabled session, and how fresh each figure is. Reads stored status by default; `--refresh` is the only path that probes a provider |
 | `cdx tray launch [--json]` | Start the installed tray companion, detached. Reports `tray_companion_not_installed` when nothing is recorded, or `tray_companion_missing` when the recorded companion is gone. `CDX_TRAY_BIN` points it at a locally built one |
-| `cdx tray install [--json]` | Download the companion for this OS and architecture, verify its published checksum before unpacking, and record what was written. Refuses when no checksum is published for the asset |
+| `cdx tray install [--json] [--yes] [--no-autostart]` | Download the companion for this OS and architecture, verify its published checksum before unpacking, record what was written, and start it. Asks whether to launch it at login — `--yes` answers without a prompt, `--no-autostart` declines, and a non-interactive run declines rather than acquiring a login item by accident. Refuses when no checksum is published for the asset |
 | `cdx tray uninstall [--json]` | Remove exactly what `install` recorded, and nothing else |
+| — | `cdx update` also moves an installed companion to the new release, and says so. A companion already running keeps executing the build it started with, so it reports that too rather than leaving you to wonder why the menu looks unchanged |
 | `cdx tray autostart [on\|off\|status] [--json]` | Start the companion at login, or stop doing so. Off until asked, idempotent, and the state is read back from the platform rather than from what CDX last intended |
 | `cdx tray events [--json]` | List agent alerts a running companion has not shown yet. The companion reads these instead of the spool file, so a Windows tray can collect events from CDX in WSL over the same interop it already uses |
 | `cdx tray ack <id>... [--json]` | Mark events as shown, idempotently |

package/changelogs/CHANGELOGS_0_18_4.md

@@ -0,0 +1,78 @@
+# CDX Manager 0.18.4
+
+## Fixes
+
+### Agent alerts arrive when they happen
+
+An alert reached the tray on the next poll, so up to thirty seconds passed
+between a turn finishing and the banner appearing — where the direct path had
+been instant. The poll period is a cost budget, not a latency target, and it was
+the wrong one for the single event a user actively waits for.
+
+The companion now notices the spool changing between polls. No file watcher was
+needed: the event loop already wakes five times a second, so a `stat` costs
+microseconds at that rate. Measured at 0.57s from hook to consumption, including
+the polling in the measurement itself.
+
+Unchanged across the Windows-to-WSL boundary, and deliberately: a Windows
+process cannot watch a path inside the Linux filesystem, so the poll period
+remains the latency there.
+
+### The menu bar icon stays visible after the first poll
+
+`tray-icon`'s macOS `set_icon` clears the template flag unconditionally, so every
+refresh dropped the setting that lets macOS invert the glyph for the current
+theme. The icon started white and turned black about thirty seconds later, which
+on a dark menu bar means invisible.
+
+### `cdx update` brings the tray companion with it
+
+The companion is a separate artifact on a separate release, so it drifted and
+had to be reinstalled by hand. `cdx update` now moves it too, through the staged
+path that verifies the asset and proves the replacement starts before the
+working one is touched — and never fails the update if it cannot: the previous
+companion stays installed and the reason is reported.
+
+`cdx tray doctor` names the state now, rather than printing two version numbers
+and leaving the comparison to you: `aligned` or `drifted`.
+
+## Features
+
+### The menu is readable at a dozen accounts
+
+Rows are selectable rather than informational — macOS renders disabled items
+grey, so a dozen arrived as a wall of grey text — and clicking one opens a
+terminal on that session. The list is sorted by urgency, most constrained first;
+it previously arrived in storage order, so an account at 1% could sit tenth
+while the icon showed critical.
+
+Sessions are grouped under their provider instead of repeating it on every row,
+and each carries a gauge. On macOS the rows are drawn: name, a gauge coloured by
+severity, and the figure aligned on a fixed column — a native menu font is
+proportional, so text alone cannot align. Windows and Linux keep the text rows,
+which say everything the drawing does.
+
+Times are distances, not stamps: `↻ in 6d 23h` rather than `↻ Aug 18 03:23`, and
+a stale row says how stale. The wording is `cdx status`'s own.
+
+### A switch to silence agent alerts
+
+In the tray menu and as `cdx tray alerts on|off|status`. Muting stops the
+banner, not the record — events keep reaching a running companion, so the menu
+shows what you missed — and it applies to the direct path too, so quitting the
+tray does not silently un-mute you.
+
+### `cdx tray install` starts what it installed
+
+And asks whether to launch it at login. `--yes` answers without a prompt,
+`--no-autostart` declines, and a non-interactive run declines too: a script must
+not acquire a startup entry by running an install.
+
+## Validation
+
+- `npm run lint`, `npm test` — 790 Python tests
+- `cargo test` — 52 Rust tests; `cargo clippy` clean with zero warnings on three
+  targets
+- 143 Python tests on native Windows, plus the Windows and Linux companions
+  exercised on a managed host: grouped menu, gauges, alert switch, spool path,
+  and the unsupported-desktop path still refusing to draw

package/checksums/release-archives.json

@@ -224,6 +224,17 @@
         "x86_64-pc-windows-msvc": "7a40ffc6a1908e0cda5e484b50ab7c11b6cb01f4c370905eefe23e40a8afb7bd",
         "x86_64-unknown-linux-musl": "2f4b95c661cdb65bf58c2aa0d2c7a45e03bb5a8ec3d20404c688887dba33afe4"
       }
+    },
+    "v0.18.3": {
+      "github_tarball_sha256": "0099b87967b2a2f4f026c97888d2017473c0b58aa974b56dd35320231e67e248",
+      "github_zip_sha256": "f6f15a9f91a85696d4f865cf192bfb4b076be92937105df57329fbfc73147631",
+      "tray_assets": {
+        "aarch64-apple-darwin": "5bbd0d9764c0feae3fc60c24951fc8202f56c8cd69574440277a4b372ae93da5",
+        "aarch64-unknown-linux-musl": "c937af7a08701fbc102ff3d7e0458e488a57001e65f20acab7809221a0395310",
+        "x86_64-apple-darwin": "036dde97929ed4c3a5e0b29b4e8332caede15c124e907c573557d888439af748",
+        "x86_64-pc-windows-msvc": "e50250d21d11e6986a310a00d4f3ab5b1a13d2960684750c569926d5bda923f9",
+        "x86_64-unknown-linux-musl": "edbdb02b7e9df5709b5b9512233e2b25b51f7652bd1b78c68edb85dbfa65d708"
+      }
     }
   }
 }

package/package.json

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

package/src/commands/maintenance.py

@@ -587,6 +587,51 @@ def handle_repair(rest, ctx):
             ctx["out"](f"{_dim('Tip: run cdx repair --force to apply safe repairs.', ctx['use_color'])}\n")
     return 0
 
+def _align_tray_companion(ctx, target_version):
+    """Move an installed tray companion to the release CDX just moved to.
+
+    Never raises and never fails the update: CDX has already been replaced
+    successfully by this point, and a companion that could not follow is a
+    warning, not a reason to call a good update bad.
+    """
+    from ..tray_install import align_companion
+    from ..tray_instance import companion_instance
+
+    try:
+        base_dir = ctx["service"]["base_dir"]
+        result = align_companion(base_dir, target_version, download=ctx.get("download_asset"))
+    except Exception as error:  # noqa: BLE001 - the update already succeeded
+        return [{"code": "tray_companion_not_aligned", "message": f"The tray companion was left as it was: {error}"}]
+
+    if not result["aligned"]:
+        if result.get("reason") in ("no companion is installed", "already aligned"):
+            return []
+        return [{
+            "code": "tray_companion_not_aligned",
+            "message": (
+                f"The tray companion is still on {result.get('previous') or 'its previous version'}: "
+                f"{result['reason']} Run: cdx tray install"
+            ),
+        }]
+
+    warnings = [{
+        "code": "tray_companion_updated",
+        "message": f"Updated the tray companion to {target_version} as well.",
+    }]
+    # A running companion keeps executing the binary it started with. Saying so
+    # beats leaving someone to wonder why the menu still looks old, and beats
+    # quitting an application they did not ask us to touch.
+    try:
+        if companion_instance(env=ctx.get("env")).get("pid"):
+            warnings.append({
+                "code": "tray_companion_restart_pending",
+                "message": "The running tray is still the previous build. Quit it from its menu and run: cdx tray launch",
+            })
+    except Exception:  # noqa: BLE001
+        pass
+    return warnings
+
+
 def handle_update(rest, ctx):
     parsed = _parse_update_args(rest)
     if parsed["all"]:
@@ -704,6 +749,12 @@ def handle_update(rest, ctx):
     if version_warning:
         warnings.append(version_warning)
 
+    # The tray companion is a separate artifact on a separate release, so it
+    # drifts unless something moves it. Reported rather than silent either way:
+    # an install that did not happen is as worth knowing as one that did.
+    for tray_warning in _align_tray_companion(ctx, target_version):
+        warnings.append(tray_warning)
+
     message = f"Updated cdx-manager to {target_version}"
     if json_flag:
         _write_json(ctx, _json_success(

package/src/commands/tray.py

@@ -27,6 +27,7 @@ from ..tray_events import (
     acknowledge as ack_events,
 )
 from ..tray_events import (
+    events_path,
     read_events,
     write_heartbeat,
 )
@@ -116,6 +117,11 @@ def _tray_status(args, ctx):
     base_dir = ctx["service"]["base_dir"]
     snapshot["events"] = read_events(base_dir)
     snapshot["alerts_enabled"] = alerts_enabled(base_dir)
+    # Where the alerts land, so a companion on this machine can watch the file
+    # instead of waiting for its next poll. Meaningless across WSL — a Windows
+    # process cannot stat a path in the Linux filesystem — and the companion
+    # ignores it there rather than CDX pretending otherwise.
+    snapshot["spool_path"] = events_path(base_dir)
     # `--beat` is what claims ownership of alerts, so it is opt-in: a caller
     # that merely looks at the status must not make `cdx notify` believe a tray
     # is listening.
@@ -199,10 +205,18 @@ def _tray_uninstall(args, ctx):
     return 0
 
 
+def _confirm_autostart():
+    answer = input("Start the CDX tray automatically at login? [Y/n] ")
+    return answer.strip().lower() in ("", "y", "yes")
+
+
 def _tray_install(args, ctx):
     parsed = _parse_flag_args(args, {
         "--json": {"key": "json", "type": "bool", "default": False},
+        "--yes": {"key": "yes", "type": "bool", "default": False},
+        "--no-autostart": {"key": "no_autostart", "type": "bool", "default": False},
     }, TRAY_USAGE, positionals_key="args", max_positionals=0)
+    env = ctx.get("env")
     target = current_target()
     if not target:
         return _refuse(
@@ -222,14 +236,50 @@ def _tray_install(args, ctx):
         raise CdxError(str(error)) from error
 
     message = f"Installed the {state['target']} tray companion for CDX {state['cdx_version']}"
+
+    # Installing something you asked for should show you the thing. The tray is
+    # started here rather than left for a second command, and a failure to start
+    # is reported without undoing an install that worked.
+    started = False
+    try:
+        spawn = ctx.get("spawn_detached") or _spawn_detached
+        spawn(launch_command(state["executable"]))
+        started = True
+    except Exception as error:  # noqa: BLE001 - the install itself succeeded
+        ctx_error = str(error)
+    else:
+        ctx_error = None
+
+    # Startup is asked for, never assumed. `req_038` AC1 originally forbade it
+    # outright, for a good reason — an install that quietly adds a login item is
+    # what people resent about desktop software. Asking keeps the reason and
+    # drops the friction; a non-interactive run declines rather than deciding.
+    autostart_on = False
+    autostart_reason = None
+    if parsed["no_autostart"]:
+        autostart_reason = "skipped with --no-autostart"
+    elif parsed["yes"] or (ctx["stdin_is_tty"] and not parsed["json"] and _confirm_autostart()):
+        try:
+            autostart_enable(state["executable"], env=env, run=ctx.get("spawn_sync"))
+            autostart_on = True
+        except Exception as error:  # noqa: BLE001
+            autostart_reason = str(error)
+    else:
+        autostart_reason = "not enabled; run: cdx tray autostart on"
+
     if parsed["json"]:
         _write_json(ctx, _json_success(
             "tray.install", message,
             target=state["target"], executable=state["executable"],
             sha256=state["sha256"], applied=True,
+            started=started, autostart=autostart_on,
         ))
         return 0
     ctx["out"](f"{message}\n{_dim(state['executable'], ctx['use_color'])}\n")
+    ctx["out"](f"{'Started it.' if started else f'It is installed but did not start: {ctx_error}'}\n")
+    ctx["out"](
+        f"{'It will start at login.' if autostart_on else f'Startup: {autostart_reason}'}\n"
+    )
     return 0
 
 
@@ -308,7 +358,12 @@ def _tray_doctor(args, ctx):
          executable or "run: cdx tray install"),
         ("executable", "present" if executable and os.path.exists(executable) else "missing",
          executable or "-"),
-        ("cdx_version", ctx["version"], (state or {}).get("cdx_version") or "-"),
+        # Named rather than left as two numbers to compare: drift is the state
+        # that makes someone reinstall by hand, and `cdx update` now fixes it,
+        # so the report should say which one you are in.
+        ("cdx_version",
+         "aligned" if not state or state.get("cdx_version") == ctx["version"] else "drifted",
+         f"cdx {ctx['version']}, companion {(state or {}).get('cdx_version') or 'not installed'}"),
         ("target", (state or {}).get("target") or "-", (state or {}).get("sha256") or "-"),
         ("running", "yes" if instance.get("pid") else "no", str(instance.get("pid") or "-")),
         ("autostart", "on" if autostart["enabled"] else "off", autostart["artifact"] or "unsupported"),

package/src/tray_contract.py

@@ -19,6 +19,7 @@ from .session_status import (
     CODEX_STATUS_CACHE_TTL_SECONDS,
     STATUS_CACHE_TTL_SECONDS,
 )
+from .status_view import _format_reset_time
 
 SCHEMA_NAME = "cdx.tray.snapshot"
 SCHEMA_MAJOR = 1
@@ -96,6 +97,26 @@ def _eligible(row):
     return row.get("enabled", True) is not False
 
 
+def _ago(seconds):
+    """How long ago, in the shortest form that stays unambiguous.
+
+    `None` when nothing was ever reported: "never" is a state the caller already
+    names, and inventing an age for it would be worse than saying nothing.
+    """
+    if seconds is None:
+        return None
+    seconds = max(0, int(seconds))
+    if seconds < 60:
+        return "just now"
+    minutes = seconds // 60
+    if minutes < 60:
+        return f"{minutes}m ago"
+    hours = minutes // 60
+    if hours < 24:
+        return f"{hours}h ago"
+    return f"{hours // 24}d ago"
+
+
 def menu_session(row, now):
     """One menu line. Everything the tray shows once the user opens it."""
     freshness, age = session_freshness(row, now)
@@ -107,6 +128,12 @@ def menu_session(row, now):
         "remaining_5h_pct": row.get("remaining_5h_pct"),
         "remaining_week_pct": row.get("remaining_week_pct"),
         "reset_at": row.get("reset_at"),
+        # The same wording `cdx status` uses — "in 5h", "passed 3h ago" — rather
+        # than a second vocabulary for the same idea. An absolute stamp costs a
+        # dozen characters per row and still makes the reader do the subtraction
+        # that matters: how long until it comes back.
+        "reset_in": _format_reset_time(row.get("reset_at")),
+        "updated_ago": _ago(age),
         "active": bool(row.get("active")),
         "state": icon_state_for_pct(row.get("available_pct")),
         "freshness": freshness,

package/src/tray_install.py

@@ -251,6 +251,34 @@ def install(base_dir, version, download=None, ledger_path=CHECKSUM_LEDGER, targe
     return state
 
 
+def align_companion(base_dir, version, download=None, ledger_path=CHECKSUM_LEDGER, target=None, env=None, probe=None):
+    """Bring an installed companion up to the CDX release that just landed.
+
+    `item_081` AC2 asks for the two to stay aligned, and until now nothing did
+    it: `cdx update` moved CDX and left the companion behind, so the user had to
+    notice the drift and reinstall by hand.
+
+    Returns a dict describing what happened, and never raises. The CDX update
+    has already succeeded by the time this runs — failing it because a companion
+    could not be replaced would undo a good outcome for a worse reason. Every
+    refusal is reported instead.
+    """
+    state = read_state(base_dir)
+    if not state:
+        return {"aligned": False, "reason": "no companion is installed"}
+    if state.get("cdx_version") == version:
+        return {"aligned": False, "reason": "already aligned"}
+    try:
+        update(base_dir, version, download=download, ledger_path=ledger_path, target=target, probe=probe)
+    except TrayInstallError as error:
+        return {
+            "aligned": False,
+            "reason": str(error),
+            "previous": state.get("cdx_version"),
+        }
+    return {"aligned": True, "previous": state.get("cdx_version"), "version": version}
+
+
 def _extract(archive, destination):
     """Unpack, refusing any member that would escape the destination.