cdx-manager 0.18.2 → 0.18.3

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.18.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.18.3-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.
 
@@ -521,6 +521,7 @@ cdx history --summary --from 2026-05-01 --to 2026-05-28
 | `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 |
 | `cdx tray heartbeat [--json]` | Record that a companion is alive. `cdx notify` publishes to the tray only while this is fresh, and delivers directly otherwise |
+| `cdx tray alerts [on\|off\|status] [--json]` | Silence agent alerts, or let them through again — the tray menu has the same switch. Muting stops the banner, not the record: events still reach a running companion, so the menu shows what you missed. It applies to the direct notification path too, so quitting the tray does not silently un-mute you. Distinct from the per-session `--notify` opt-in, which says which sessions may alert at all |
 | `cdx tray doctor [--json]` | Report companion, executable, version, running instance, autostart, and the two capabilities that fail silently — whether this desktop can draw a tray icon at all, and on Windows whether the Start Menu shortcut toasts depend on exists. Reads only; it never repairs |
 | `cdx --help` | Show usage |
 | `cdx --version` | Show version |

package/changelogs/CHANGELOGS_0_18_3.md

@@ -0,0 +1,63 @@
+# CDX Manager 0.18.3
+
+## Fixes
+
+### Agent alerts reach the tray companion
+
+A running companion never received an agent alert. Notifications still arrived,
+delivered the old way, and nothing reported an error — which is why it took
+watching a real machine to notice.
+
+`CDX_HOME` defaults to `~/.cdx`, resolved against `HOME`, and a provider session
+runs with `HOME` redirected into its own profile because that is how cdx isolates
+authentication. So a hook calling `cdx notify` resolved a different store from
+the one the companion writes its heartbeat into: no heartbeat there, no tray,
+deliver it directly. Both stores existed side by side on disk.
+
+The launch environment now pins `CDX_HOME` explicitly, so a hook talks to the
+same store whatever `HOME` it runs under. This takes effect for sessions started
+after the upgrade; a session already open keeps the environment it was launched
+with.
+
+### The macOS menu bar icon stays visible
+
+The icon started white and turned black about thirty seconds later, which on a
+dark menu bar means invisible. `tray-icon`'s macOS `set_icon` clears the template
+flag unconditionally, so every poll dropped the setting that lets macOS invert
+the glyph for the current theme. It is now re-asserted after each update.
+
+Not a bug, and worth separating: while the menu is open macOS highlights the
+status item and inverts a template image, so the icon is meant to look dark
+there.
+
+## Features
+
+### A switch to silence agent alerts
+
+The tray menu carries a checkmark item, and `cdx tray alerts on|off|status` does
+the same from a terminal.
+
+Muting stops the banner, not the record: events keep reaching a running
+companion, so the menu shows what you missed. It applies to the direct
+notification path too, so quitting the tray does not silently un-mute you. It is
+separate from the per-session `--notify` opt-in, which says which sessions may
+alert at all.
+
+### A readable tray menu
+
+Session rows are selectable rather than informational — macOS renders disabled
+items grey, so a dozen of them arrived as a wall of grey text. 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 closed icon showed
+critical: the menu buried the very thing that made you open it.
+
+## Validation
+
+- `npm run lint`
+- `npm test` — 782 Python tests
+- `cargo test` — 45 Rust tests; `cargo clippy` clean with zero warnings on three
+  targets
+- The tray menu, its switch and the notification routing exercised against real
+  sessions on macOS

package/checksums/release-archives.json

@@ -213,6 +213,17 @@
         "x86_64-pc-windows-msvc": "738eeb165c1c2fde58bd952cdc0a59561ca96856a3fb8d0cffc024bfb78b9ca6",
         "x86_64-unknown-linux-musl": "0b3c02b007aa0655a5b95c7794eba49a37bdb9868c447bb0cfbdfbd9d371d094"
       }
+    },
+    "v0.18.2": {
+      "github_tarball_sha256": "c988bf1462e8b707394c787c2a78ce2f4af9f1e88d79e71fdf61e70fd3945430",
+      "github_zip_sha256": "82a211118f29385b92b19e14df5fa344455b247930b30b4c700976867eee6527",
+      "tray_assets": {
+        "aarch64-apple-darwin": "2a250f4b49011c90a16adcda76cce49b1191e744dfae0997cf394b0a345efd70",
+        "aarch64-unknown-linux-musl": "efeb6a60677f039e411865454e60693c0c42253b9d32afd44d69a4a8905d891c",
+        "x86_64-apple-darwin": "f163caa8149ef4cd6061904f3d28c00b24dc93908667bb86da57c51cdf41ab4f",
+        "x86_64-pc-windows-msvc": "7a40ffc6a1908e0cda5e484b50ab7c11b6cb01f4c370905eefe23e40a8afb7bd",
+        "x86_64-unknown-linux-musl": "2f4b95c661cdb65bf58c2aa0d2c7a45e03bb5a8ec3d20404c688887dba33afe4"
+      }
     }
   }
 }

package/package.json

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

package/src/agent_notify.py

@@ -14,7 +14,9 @@ import os
 import shutil
 import subprocess
 
+from .config import get_cdx_home
 from .notify import notification_channel, send_desktop_notification
+from .tray_alerts import alerts_enabled
 from .tray_events import publish
 
 # Set on the provider process at launch; the hook runs as its child and inherits both.
@@ -120,6 +122,14 @@ def handle_notify(rest, ctx):
         payload = read_hook_payload(rest, stdin_text)
         composed = compose_notification(payload, env, ctx.get("cwd"))
         if composed:
+            # Muted stops the banner, not the record: the event still reaches a
+            # running tray so the menu can show what was missed, and the direct
+            # path stays quiet too — otherwise quitting the tray would un-mute.
+            base_dir = (ctx.get("service") or {}).get("base_dir")
+            muted = bool(base_dir) and not alerts_enabled(base_dir)
+            if muted:
+                _published_to_tray(ctx, composed, payload)
+                return 0
             # A live tray becomes the sole owner of this alert, so the user sees
             # one notification rather than two. Publication happens below the
             # composition boundary on purpose: the tray receives the same
@@ -133,8 +143,18 @@ def handle_notify(rest, ctx):
 
 
 def launch_notify_env(session, enabled, env=None):
-    """Env the provider is launched with, carrying who we are and whether to notify."""
-    values = {SESSION_ENV: session["name"]}
+    """Env the provider is launched with, carrying who we are and whether to notify.
+
+    `CDX_HOME` is pinned rather than inherited, and that is what makes tray
+    routing work at all. It defaults to `~/.cdx`, resolved against `HOME` — and
+    a provider session runs with `HOME` redirected into its own profile, which
+    is how cdx isolates auth. So a hook calling `cdx notify` would resolve a
+    *different* store from the one the companion writes its heartbeat into, find
+    no tray, and quietly deliver the notification itself. The symptom is a
+    running tray that never receives an alert, with nothing reporting an error.
+    """
+    env = os.environ if env is None else env
+    values = {SESSION_ENV: session["name"], "CDX_HOME": get_cdx_home(env)}
     if not enabled:
         values[ENABLED_ENV] = "0"
     elif (session.get("launch") or {}).get("notify_preview") is True:

package/src/cli_args.py

@@ -63,7 +63,7 @@ RUN_STATUS_USAGE = "Usage: cdx run-status <run_id> --json"
 RUN_REPORT_USAGE = "Usage: cdx run-report <run_id> --json"
 RUN_TAIL_USAGE = "Usage: cdx run-tail <run_id> [--lines N] --json"
 SCHEMA_USAGE = "Usage: cdx schema --json"
-TRAY_USAGE = "Usage: cdx tray status [--json] [--refresh] [--beat] | cdx tray install|launch|uninstall|doctor [--json] | cdx tray autostart [on|off|status] [--json] | cdx tray events [--json] | cdx tray ack <id>... [--json] | cdx tray heartbeat [--json]"
+TRAY_USAGE = "Usage: cdx tray status [--json] [--refresh] [--beat] | cdx tray install|launch|uninstall|doctor [--json] | cdx tray autostart [on|off|status] [--json] | cdx tray events [--json] | cdx tray ack <id>... [--json] | cdx tray heartbeat [--json] | cdx tray alerts [on|off|status] [--json]"
 
 RUN_TAIL_DEFAULT_LINES = 50
 RUN_TAIL_MAX_LINES = 2000

package/src/commands/tray.py

@@ -12,6 +12,7 @@ from ..cli_args import TRAY_USAGE, _parse_flag_args
 from ..cli_helpers import _json_success, _write_json
 from ..cli_render import _dim, _pad_table, _style, _warn
 from ..errors import CdxError
+from ..tray_alerts import alerts_enabled, set_alerts
 from ..tray_autostart import disable as autostart_disable
 from ..tray_autostart import enable as autostart_enable
 from ..tray_autostart import status as autostart_status
@@ -41,7 +42,10 @@ from ..tray_install import (
 )
 from ..tray_instance import companion_instance
 
-TRAY_ACTIONS = ("status", "install", "launch", "uninstall", "autostart", "doctor", "events", "ack", "heartbeat")
+TRAY_ACTIONS = (
+    "status", "install", "launch", "uninstall", "autostart", "doctor",
+    "events", "ack", "heartbeat", "alerts",
+)
 
 # Codes rather than prose, so a caller can branch on them.
 COMPANION_UNAVAILABLE = "tray_companion_not_available"
@@ -79,6 +83,8 @@ def handle_tray(rest, ctx):
         return _tray_ack(args, ctx)
     if action == "heartbeat":
         return _tray_heartbeat(args, ctx)
+    if action == "alerts":
+        return _tray_alerts(args, ctx)
     return _tray_install(args, ctx)
 
 
@@ -109,6 +115,7 @@ def _tray_status(args, ctx):
     # needs.
     base_dir = ctx["service"]["base_dir"]
     snapshot["events"] = read_events(base_dir)
+    snapshot["alerts_enabled"] = alerts_enabled(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.
@@ -292,7 +299,7 @@ def _tray_doctor(args, ctx):
     executable, source = companion_path(base_dir, env=env)
     state = read_state(base_dir)
     autostart = autostart_status(env=env, run=ctx.get("spawn_sync"))
-    instance = companion_instance()
+    instance = companion_instance(env=env)
     desktop = desktop_capability(env=env)
     toasts = toast_capability(env=env)
 
@@ -305,6 +312,8 @@ def _tray_doctor(args, ctx):
         ("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"),
+        ("alerts", "on" if alerts_enabled(base_dir) else "muted",
+         "cdx tray alerts on|off"),
         ("update", "interrupted" if interrupted_update(base_dir) else "clean",
          "a staged companion was never promoted; run: cdx tray install"
          if interrupted_update(base_dir) else "-"),
@@ -443,3 +452,31 @@ def _tray_heartbeat(args, ctx):
         return 0
     ctx["out"]("Recorded the tray heartbeat.\n")
     return 0
+
+
+def _tray_alerts(args, ctx):
+    """Silence agent alerts, or let them through again.
+
+    Separate from the per-session `--notify` preference on purpose: that says
+    which sessions may alert at all, and spending it to go quiet for a meeting
+    would be a poor trade. This is the temporary switch, and it is reported
+    rather than remembered — `cdx tray doctor` reads it back.
+    """
+    parsed = _parse_flag_args(args, {
+        "--json": {"key": "json", "type": "bool", "default": False},
+    }, TRAY_USAGE, positionals_key="args", max_positionals=1)
+    mode = (parsed["args"] or ["status"])[0]
+    if mode not in ("on", "off", "status"):
+        raise CdxError(TRAY_USAGE)
+    base_dir = ctx["service"]["base_dir"]
+    if mode != "status":
+        set_alerts(base_dir, mode == "on")
+    enabled = alerts_enabled(base_dir)
+    message = f"Agent alerts are {'on' if enabled else 'muted'}"
+    if parsed["json"]:
+        _write_json(ctx, _json_success(
+            "tray.alerts", message, enabled=enabled, applied=mode != "status",
+        ))
+        return 0
+    ctx["out"](f"{message}\n")
+    return 0

package/src/tray_alerts.py

@@ -0,0 +1,55 @@
+"""Whether agent alerts may raise a banner right now.
+
+A quick way to go quiet during a meeting or a screen share, and back afterwards,
+without touching the per-session `--notify` preferences — those say which
+sessions may alert at all, and losing them to a temporary mute would be a poor
+trade for two minutes of silence.
+
+Two decisions are worth stating because they are what make it a *silence*:
+
+  - Muting stops the banner, not the recording. Events keep arriving in the
+    tray's recent list, so the menu is where you catch up on what you missed.
+    An switch that dropped them would be an off, not a mute.
+  - It applies to the direct notification path too, not only to a running tray.
+    Otherwise quitting the companion would silently un-mute you, which is
+    exactly the kind of surprise a mute exists to prevent.
+
+Stored in CDX's own home rather than in the companion, because the hook is what
+reads it and the hook is not the tray.
+"""
+import json
+import os
+
+STATE_VERSION = 1
+
+
+def state_path(base_dir):
+    return os.path.join(base_dir, "tray", "alerts.json")
+
+
+def alerts_enabled(base_dir):
+    """On unless explicitly muted.
+
+    Anything unreadable or unrecognised reads as on. A mute that outlived a
+    damaged file would silence someone with no way to see why, and silence is
+    the failure that hides itself.
+    """
+    try:
+        with open(state_path(base_dir), encoding="utf-8") as handle:
+            state = json.load(handle)
+    except (OSError, ValueError):
+        return True
+    if not isinstance(state, dict) or state.get("version") != STATE_VERSION:
+        return True
+    return state.get("enabled") is not False
+
+
+def set_alerts(base_dir, enabled):
+    """Mute or unmute, and report what it now is."""
+    path = state_path(base_dir)
+    os.makedirs(os.path.dirname(path), exist_ok=True)
+    temp = f"{path}.{os.getpid()}.tmp"
+    with open(temp, "w", encoding="utf-8") as handle:
+        json.dump({"version": STATE_VERSION, "enabled": bool(enabled)}, handle, indent=2)
+    os.replace(temp, path)
+    return bool(enabled)

package/src/tray_contract.py

@@ -115,6 +115,29 @@ def menu_session(row, now):
     }
 
 
+def _by_urgency(sessions):
+    """Most constrained first, so the menu opens on what the icon is warning about.
+
+    The order the rows arrive in is the store's, which is not the order a person
+    reads for. With a dozen accounts the one at 1% sat tenth, below five at
+    100%, while the closed icon showed critical — the menu contradicted the
+    thing that made you open it.
+
+    Same ranking the icon uses, for the same reason: severity first, then least
+    remaining, and never-reported last. A session that never reported is not
+    urgent, it is unknown, and putting it on top would bury real news.
+    """
+    severity = {ICON_CRITICAL: 0, ICON_LOW: 1, ICON_OK: 2, ICON_UNKNOWN: 3}
+    return sorted(
+        sessions,
+        key=lambda s: (
+            severity[s["state"]],
+            s["available_pct"] if s["available_pct"] is not None else 101,
+            s["name"] or "",
+        ),
+    )
+
+
 def _worst(sessions):
     """The session whose state the closed icon should show.
 
@@ -179,7 +202,7 @@ def build_snapshot(rows, now, cdx_version, refreshable=True):
     `icon` carries no session name, account, or figure: it is what shows while
     the menu is closed, and `req_035` AC3 forbids leaking anything there.
     """
-    sessions = [menu_session(row, now) for row in rows if _eligible(row)]
+    sessions = _by_urgency([menu_session(row, now) for row in rows if _eligible(row)])
     if not sessions:
         icon = {
             "state": ICON_UNKNOWN,