cdx-manager 0.18.2 → 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.2-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,12 +519,14 @@ 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 |
 | `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/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

@@ -213,6 +213,28 @@
         "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"
+      }
+    },
+    "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.2",
+  "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.2"
+version = "0.18.4"
 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/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

@@ -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
@@ -26,6 +27,7 @@ from ..tray_events import (
     acknowledge as ack_events,
 )
 from ..tray_events import (
+    events_path,
     read_events,
     write_heartbeat,
 )
@@ -41,7 +43,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 +84,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 +116,12 @@ 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)
+    # 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.
@@ -192,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(
@@ -215,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
 
 
@@ -292,7 +349,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)
 
@@ -301,10 +358,17 @@ 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"),
+        ("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 +507,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

@@ -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,
@@ -115,6 +142,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 +229,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,

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.