cdx-manager 0.18.1 → 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.1-4C8BF5) ![Python](https://img.shields.io/badge/python-3.9%2B-3776AB?logo=python&logoColor=white)
+[![License](https://img.shields.io/badge/license-MIT-4C8BF5)](LICENSE) ![Version](https://img.shields.io/badge/version-v0.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 |
@@ -560,6 +561,7 @@ They are deliberately hard to become noise. One hint per invocation at most, not
 
 The companion is a native binary distributed as a release asset, not part of the pip package. Its trust model is worth stating plainly rather than leaving you to assume the usual one.
 
+- **Where the checksum comes from.** Releases older than the one you are running are vouched for by `checksums/release-archives.json`, committed to the repository before those assets existed. Your own release is a special case: its tray assets are built after the tag, so no package built at tag time can carry their checksums. For that one version CDX reads the ledger the release publishes beside the assets — the publisher's own assertion over the same channel, which catches a truncated download or a wrong-architecture asset but does not defend against someone who can rewrite the release itself.
 - **The checksum is the vouching, not Apple or Microsoft.** The macOS bundle is signed with a *self-signed* certificate. That signature exists because Apple Silicon refuses to execute unsigned arm64 code at all — it is not a claim that Apple reviewed anything. What actually vouches for the asset is the SHA-256 published in `checksums/release-archives.json`, verified before a single byte is unpacked. An asset with no published checksum is refused rather than installed hopefully.
 - **Install through `cdx tray install`, and no download link is offered.** This is a security property, not a convenience. A file fetched by CDX carries no macOS quarantine attribute and no Windows Mark-of-the-Web, so nothing puts Gatekeeper or SmartScreen between you and a companion you asked for. The same file fetched through a browser would carry both. That is why no direct download URL is published: it would be a worse path wearing the same clothes.
 - **Nothing is silently replaced.** An update downloads, verifies, and *proves the replacement starts* before the working companion is touched. A corrupt asset or one built for the wrong architecture costs an error message, not a tray you can no longer launch. An interrupted update is a named, recoverable state that `cdx tray doctor` reports.

package/changelogs/CHANGELOGS_0_18_2.md

@@ -0,0 +1,43 @@
+# CDX Manager 0.18.2
+
+## Fixes
+
+### `cdx tray install` can install the companion for the release you are running
+
+No release could ever install its own tray companion, and the cause was
+structural rather than a bug. Tray assets are built after the tag exists, so
+their checksums are recorded afterwards — which means a package built at tag
+time ships a checksum ledger that stops at the previous release. Installing
+refused with "No published checksum for … of CDX <this version>".
+
+The release already publishes `release-archives.json` beside the assets. A
+missing local entry now falls through to it.
+
+What that is worth, stated plainly: it is the publisher's own assertion fetched
+over the same HTTPS channel as the asset, so it does not defend against someone
+able to rewrite the release. It does defend against a truncated download and an
+asset built for another architecture, which are the failures that happen. A
+checksum committed to the repository before the asset existed is the stronger
+claim, so a local entry always wins and fetches nothing.
+
+### The PyPI package can start
+
+`pyproject.toml` declared only the root package, so `cdx_manager.commands` was
+absent from every wheel since it was extracted and `pip install cdx-manager`
+produced a CLI that failed at import. setuptools does not warn about a
+subpackage it was never told about: the wheel builds cleanly and breaks on the
+user's machine.
+
+The npm package and the standalone installer were unaffected — both ship the
+source tree wholesale.
+
+A test now asserts every package under `src/` is declared for the wheel.
+
+## Validation
+
+- `npm run lint`
+- `npm test` — 775 Python tests
+- A wheel built from this tree installs into a clean virtualenv and runs
+  `cdx --version` and `cdx tray doctor`
+- `cdx tray install` exercised against a checksum ledger with no entry for the
+  version, which is the shape every shipped package has

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

@@ -202,6 +202,28 @@
         "x86_64-pc-windows-msvc": "86e29cbdbcf070aec7fd34e5596343a43f2b5092e634ca094aba96abf1d49884",
         "x86_64-unknown-linux-musl": "36ef879c0e75f3c367ed48f1f5a67e25698ec5a04c70958b48ae0885f87487d8"
       }
+    },
+    "v0.18.1": {
+      "github_tarball_sha256": "260529247233abca840ecba03c2948234425b4fe0d27f2e5c008bdeb89fb0bd5",
+      "github_zip_sha256": "bc14fc2fd27641a56089a023b51427abac854eaf527a17d9bc0571698fb19b9f",
+      "tray_assets": {
+        "aarch64-apple-darwin": "8a1cd7f819d21097d63f8c452479bae7bfbfe3468473c7e8f557043c7b7ab47c",
+        "aarch64-unknown-linux-musl": "a4a757bfc0f048aa24439b675cb9f269d70328a98be88efbe5cc3fea96cbd78d",
+        "x86_64-apple-darwin": "1003b7051d6dfbf1a19c1e82eca1c648d11363171a77ad0cd85822a167921573",
+        "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.1",
+  "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.1"
+version = "0.18.3"
 description = "Terminal session manager for Codex and Claude accounts."
 readme = "README.md"
 requires-python = ">=3.9"
@@ -45,10 +45,17 @@ Changelog = "https://github.com/AlexAgo83/cdx-manager/tree/main/changelogs"
 cdx = "cdx_manager.cli:cli_entry"
 
 [tool.setuptools]
-packages = ["cdx_manager"]
+# Every package under src/, not just the root. Subpackages have to be named
+# explicitly here, and one that is missing is not a build error: the wheel is
+# produced happily and fails at import on the user's machine. src/commands has
+# been absent from every wheel since it was extracted, so `pip install
+# cdx-manager` gave an unusable CLI while the npm and standalone installs — both
+# of which ship the source tree wholesale — worked fine.
+packages = ["cdx_manager", "cdx_manager.commands"]
 
 [tool.setuptools.package-dir]
 cdx_manager = "src"
+"cdx_manager.commands" = "src/commands"
 
 [tool.pytest.ini_options]
 testpaths = ["test"]

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,

package/src/tray_install.py

@@ -60,19 +60,61 @@ def asset_name(version, target):
     return f"cdx-tray-{version}-{target}.tar.gz"
 
 
-def expected_checksum(version, target, ledger_path=CHECKSUM_LEDGER):
+RELEASE_LEDGER_URL = (
+    "https://github.com/AlexAgo83/cdx-manager/releases/download/v{version}/release-archives.json"
+)
+
+
+def _ledger_entry(ledger, version, target):
+    release = (ledger.get("releases") or {}).get(f"v{version}") or {}
+    return (release.get("tray_assets") or {}).get(target)
+
+
+def expected_checksum(version, target, ledger_path=CHECKSUM_LEDGER, download=None):
     """The published sha256 for this asset, or None when none is recorded.
 
     None is a refusal, not a fallback. An asset with no published checksum is
     exactly the case this gate exists for.
+
+    The shipped ledger cannot contain the entry for its own release, and that is
+    structural rather than an oversight: the tray assets are built after the tag
+    exists, so their checksums are recorded afterwards. A package built at tag
+    time therefore ships a ledger that stops at the previous release, and
+    `cdx tray install` would refuse the companion for the very version the user
+    is running.
+
+    So a missing local entry falls through to the ledger the release publishes
+    alongside the assets. Be clear about what that is worth: it is the
+    publisher's own assertion, fetched over the same HTTPS channel as the asset,
+    so it does not defend against someone who can rewrite the release. It does
+    defend against a truncated or corrupted download and against an asset built
+    for another architecture, which are the failures that actually happen. The
+    strong guarantee — a checksum committed before the asset existed — is what
+    the local ledger gives for every release older than this one.
     """
     try:
         with open(ledger_path, encoding="utf-8") as handle:
             ledger = json.load(handle)
     except (OSError, ValueError):
-        return None
-    release = (ledger.get("releases") or {}).get(f"v{version}") or {}
-    return (release.get("tray_assets") or {}).get(target)
+        ledger = {}
+    local = _ledger_entry(ledger, version, target)
+    if local:
+        return local
+    return _published_checksum(version, target, download=download)
+
+
+def _published_checksum(version, target, download=None):
+    """The entry from the ledger attached to the release, or None."""
+    fetch = download or _download
+    with tempfile.TemporaryDirectory(prefix="cdx-tray-ledger-") as scratch:
+        destination = os.path.join(scratch, "release-archives.json")
+        try:
+            fetch(RELEASE_LEDGER_URL.format(version=version), destination)
+            with open(destination, encoding="utf-8") as handle:
+                published = json.load(handle)
+        except (OSError, ValueError):
+            return None
+    return _ledger_entry(published, version, target)
 
 
 def _sha256(path):
@@ -147,7 +189,7 @@ def install(base_dir, version, download=None, ledger_path=CHECKSUM_LEDGER, targe
         raise TrayInstallError(
             f"No tray companion is published for {platform.system()} {platform.machine()}."
         )
-    expected = expected_checksum(version, target, ledger_path=ledger_path)
+    expected = expected_checksum(version, target, ledger_path=ledger_path, download=download)
     if not expected:
         raise TrayInstallError(
             f"No published checksum for the {target} tray companion of CDX {version}. "