cdx-manager 0.17.1 → 0.18.1

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.17.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.1-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.
 
@@ -513,11 +513,60 @@ cdx history --summary --from 2026-05-01 --to 2026-05-28
 | `cdx status [--json] [--refresh\|--cached] [--timeout SECONDS]` | Show token usage table for all sessions; `--cached` skips live provider probes and returns only stored status |
 | `cdx status --small [--refresh\|--cached] [--timeout SECONDS]` / `cdx status -s [--refresh\|--cached] [--timeout SECONDS]` | Show compact token usage table without provider, blocking quota, credits, and updated columns |
 | `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 uninstall [--json]` | Remove exactly what `install` recorded, and nothing else |
+| `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 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 |
 
 ---
 
+### Tray snapshot
+
+`cdx tray status --json` is the contract an optional desktop tray companion reads. It adds nothing to the quota pipeline: it interprets the status CDX already stores.
+
+- **Cached by default.** A tray polls, and a live provider probe serializes on the Codex auth lock, which the launcher holds for a whole interactive session. Polling it would be locked out at best and race a rotating OAuth refresh token at worst. Only `--refresh`, a deliberate user gesture, probes.
+- **Freshness is a value, not an error.** Each session reports `fresh`, `stale`, `auth_locked`, or `unknown`. `auth_locked` means a session is running and its quota cannot be refreshed until it exits — pressing refresh will not help, and the snapshot says so instead of ageing silently.
+- **The icon leaks nothing.** `icon` holds a state, a reason, and a count. Session names, providers, and figures live in `sessions`, which a companion shows only once the user opens the menu.
+- **Versions drift on purpose.** The payload carries `schema.major`. A reader meeting a newer major keeps every field it understands and surfaces one update hint, so upgrading CDX never breaks an installed companion.
+
+```json
+{
+  "schema": { "name": "cdx.tray.snapshot", "major": 1, "minor": 0 },
+  "icon": { "state": "low", "reason": "fresh", "session_count": 2 },
+  "sessions": [
+    { "name": "work", "provider": "codex", "available_pct": 18, "state": "low", "freshness": "fresh", "reset_at": "..." }
+  ],
+  "refreshable": true,
+  "actions": ["refresh", "open_terminal"]
+}
+```
+
+Icon states are `ok` at 25% remaining and above, `low` below 25%, `critical` below 5%, and `unknown` when nothing was ever reported. The closed icon shows the most urgent session, and a session that never reported never outranks one with real news.
+
+### Setup hints
+
+`cdx` and `cdx status` may end with one dim line pointing at an optional surface you have not set up yet — the tray companion, or agent alerts. They exist because neither is discoverable from the output of the commands you already run.
+
+They are deliberately hard to become noise. One hint per invocation at most, not again for six hours, and each one retires for good after three showings: if you saw it three times and did not act, that is an answer. A hint never appears in `--json`, never appears alongside an update notice, and is answered entirely from local state — nothing here probes a provider or the network. `CDX_NO_HINTS=1` turns them off outright.
+
+### Tray companion: what vouches for it
+
+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.
+
+- **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.
+- **Uninstall removes only what install recorded**, from a record CDX wrote itself. A damaged record reads as absent rather than being guessed at, because that record drives deletion.
+- **Linux carries no C library.** The Linux asset is statically linked against musl, so there is no glibc version to match and no `gtk`, `libxdo`, or `appindicator` package to install. Tray support is resolved at runtime by looking for the `org.kde.StatusNotifierWatcher` D-Bus name — never by matching a distribution or desktop name. A session without it is told so, and nothing is registered to start at login.
+- **Version drift between CDX and the companion is normal**, since pip upgrades one and `cdx tray install` the other. Whichever is older keeps serving every field it understands and shows one update hint.
+
 ## JSON Output
 
 `cdx-manager` can be consumed by other apps through its CLI JSON contract.

package/changelogs/CHANGELOGS_0_18_0.md

@@ -0,0 +1,82 @@
+# CDX Manager 0.18.0
+
+## Features
+
+### An optional desktop tray companion
+
+A native menu bar companion now shows remaining quota across every enabled
+session without a terminal open. It is optional, off until installed, and adds
+nothing to the quota pipeline: it reads the status CDX already stores through
+`cdx tray status --json`.
+
+`cdx tray` gained `status`, `install`, `launch`, `uninstall`, `autostart`,
+`doctor`, `events`, `ack`, and `heartbeat`.
+
+The polling is cached by default and never probes a provider on a timer. A live
+probe serializes on the Codex auth lock, which an interactive session holds for
+its whole run, and races a rotating OAuth refresh token. Only an explicit
+refresh — a user gesture from the menu — probes, and the menu says so when a
+running session makes refreshing pointless.
+
+Freshness is reported rather than hidden. Each session reads `fresh`, `stale`,
+`auth_locked`, or `unknown`, and a figure is never invented for a state that
+knows nothing.
+
+### Agent alerts delivered through the tray
+
+When a companion is running, an agent finishing a turn raises one notification
+from the tray instead of two from the tray and the direct path. The tray keeps a
+bounded list of recent alerts and marks new ones beside the icon for 45 seconds.
+
+Delivery falls back to the previous direct path whenever a companion is absent,
+stale, or speaks a schema this CDX does not, so upgrading one side never leaves
+the other silent.
+
+On macOS the alert is posted from the signed CDX bundle, so it carries the CDX
+name and icon and can be turned off under CDX in System Settings. On Windows it
+goes out under CDX's own AppUserModelID once `cdx tray install` has written the
+Start Menu shortcut, and under PowerShell's identifier until then.
+
+### Setup hints in `cdx` and `cdx status`
+
+Both commands may end with one dim line pointing at an optional surface not yet
+set up — the tray companion, or agent alerts. One hint per invocation, not again
+for six hours, retired for good after three showings, never in `--json`, never
+alongside an update notice, and `CDX_NO_HINTS=1` turns them off.
+
+## Platform support
+
+- **macOS**: signed bundle, menu bar item, native notifications, LaunchAgent
+  autostart.
+- **Windows**: taskbar icon that picks its glyph tint from the taskbar theme,
+  promotes itself out of the notification overflow once, and reads CDX from WSL
+  through interop with no X server and no localhost.
+- **Linux**: StatusNotifierItem through ksni, resolved at runtime by looking for
+  `org.kde.StatusNotifierWatcher` rather than by matching a distribution name. A
+  desktop without one is told so instead of being left with an invisible icon.
+  The asset is statically linked against musl, so there is no glibc version to
+  match and no gtk, libxdo, or appindicator package to install.
+
+## Trust model
+
+`cdx tray install` fetches a release asset and verifies its published SHA-256
+before a single byte is unpacked. The macOS bundle is self-signed: that
+signature exists because Apple Silicon refuses to execute unsigned arm64 code,
+not because Apple reviewed anything, and the published checksum is what vouches
+for the asset. Installing through CDX is also what keeps the file free of the
+macOS quarantine attribute and the Windows Mark of the Web, which is why no
+browser download link is published.
+
+An update downloads, verifies, and proves the replacement starts before the
+working companion is touched. A failure leaves the previous one running, and
+`cdx tray doctor` names the interrupted state.
+
+## Validation
+
+- `npm run lint`
+- `npm test` — 766 Python tests
+- `cargo test` — 45 Rust tests; `cargo clippy` clean with zero warnings on
+  aarch64-apple-darwin, x86_64-pc-windows-msvc, and x86_64-unknown-linux-gnu
+- `scripts/tray-smoke.sh` on three hosts: macOS arm64 native, Windows serving
+  CDX through Ubuntu WSL, and Linux natively in that same WSL
+- `logics-manager lint` and `logics-manager audit`

package/changelogs/CHANGELOGS_0_18_1.md

@@ -0,0 +1,50 @@
+# CDX Manager 0.18.1
+
+## Fixes
+
+### `cdx tray install` works against a published release
+
+0.18.0 shipped a tray installer that refused every asset the release published.
+Three separate causes, each of which only appeared when installing from a real
+release rather than from a locally built archive.
+
+**The archive shape was rejected.** Release assets are written with
+`tar -C dir .`, so they carry a member for the directory itself. The guard that
+refuses an archive escaping its install directory treated that member as an
+escape, when it resolves to the destination and nothing else. The destination is
+now accepted; an archive that genuinely writes outside its directory is still
+refused, and a link member still is.
+
+**Windows asked for an asset nobody builds.** CDX looked for
+`x86_64-pc-windows-gnu` while releases are built with the MSVC toolchain, so no
+published checksum ever matched the name it asked for. Every Windows install
+refused for want of a checksum that was published under a different target.
+
+**ARM Linux was offered and never built.** `aarch64-unknown-linux-musl` was a
+target CDX would install and the release did not produce. It is now built and
+published alongside the others.
+
+A test now asserts that every target CDX offers is one the release actually
+builds, so this class of mismatch fails in CI rather than on a user's machine.
+
+### Windows toasts carry the CDX icon
+
+The Start Menu shortcut CDX installs now points at an icon shipped with the
+companion, so a notification shows the CDX logo rather than a generic one.
+Uninstall removes the shortcut along with the companion.
+
+## Release safety
+
+Publishing to npm and PyPI now waits for the tray companion assets to build
+successfully. All four workflows fire on the same release event, so previously
+they ran beside each other: a failed asset build would have left both registries
+carrying a version whose release had no companion to install.
+
+## Validation
+
+- `npm run lint`
+- `npm test` — 771 Python tests
+- `cargo test` — 45 Rust tests; `cargo clippy` clean with zero warnings on three
+  targets
+- `cdx tray install`, `doctor`, `launch` and `uninstall` exercised against the
+  published v0.18.0 assets on macOS arm64, Windows, and Linux under WSL

package/checksums/release-archives.json

@@ -188,6 +188,20 @@
     "v0.17.0": {
       "github_tarball_sha256": "6f321106aa426590ce809788fab4f26401b4cc499a6c518a56a4f24f8bfb6c2e",
       "github_zip_sha256": "72665a0006df40bb27301140b0ed6600a0d91b456facbb5a2aad2a917357ae75"
+    },
+    "v0.17.1": {
+      "github_tarball_sha256": "f1cc36d55f17d8e5c8ad0b0ebc419e812b8788742c3e45ce1137303924114dd7",
+      "github_zip_sha256": "29acb306ad76535d0db701504a53b9887b8a6b0b95d968634139f85952a34ec3"
+    },
+    "v0.18.0": {
+      "github_tarball_sha256": "ae666d8ec38a74859e1edc5023101474a2fb647ecb3ba285fd746c7b84699854",
+      "github_zip_sha256": "72ecdd02b449c2256a74f77afec7eda8cd9b53b52bb62858e45d3d6000a1bd24",
+      "tray_assets": {
+        "aarch64-apple-darwin": "45aa98624bda29dea26637aeb22a86b22fe018a95fb176bfffd3504c772c9988",
+        "x86_64-apple-darwin": "d310852919cd4e2ddce2108044d0039e088b5bdc3dfa029be4d81ee0df1c420b",
+        "x86_64-pc-windows-msvc": "86e29cbdbcf070aec7fd34e5596343a43f2b5092e634ca094aba96abf1d49884",
+        "x86_64-unknown-linux-musl": "36ef879c0e75f3c367ed48f1f5a67e25698ec5a04c70958b48ae0885f87487d8"
+      }
     }
   }
 }

package/package.json

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

package/src/agent_notify.py

@@ -15,6 +15,7 @@ import shutil
 import subprocess
 
 from .notify import notification_channel, send_desktop_notification
+from .tray_events import publish
 
 # Set on the provider process at launch; the hook runs as its child and inherits both.
 SESSION_ENV = "CDX_SESSION_NAME"
@@ -116,9 +117,16 @@ def handle_notify(rest, ctx):
             return 0
         if reader is not None and not ctx.get("stdin_is_tty"):
             stdin_text = reader.read()
-        composed = compose_notification(read_hook_payload(rest, stdin_text), env, ctx.get("cwd"))
+        payload = read_hook_payload(rest, stdin_text)
+        composed = compose_notification(payload, env, ctx.get("cwd"))
         if composed:
-            send_desktop_notification(*composed, spawn_sync=ctx.get("spawn_sync"), env=env)
+            # 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
+            # already-sanitized title and message the direct path would send,
+            # and cannot be handed anything the privacy rules removed.
+            if not _published_to_tray(ctx, composed, payload):
+                send_desktop_notification(*composed, spawn_sync=ctx.get("spawn_sync"), env=env)
     except Exception:  # noqa: BLE001 - deliberate: the caller is an agent turn
         pass
     return 0
@@ -357,3 +365,24 @@ def _write_json(path, document):
         # An unwritable home is a skipped provisioning step, not a failed launch.
         return False
     return True
+
+
+def _published_to_tray(ctx, composed, payload):
+    """Hand the alert to a live tray, or say we did not.
+
+    False is the safe answer to everything: no base directory, no heartbeat, a
+    stale one, a schema mismatch, or an unwritable spool all mean the direct
+    path still runs. The only way to lose a notification here would be to
+    return True without having written it.
+    """
+    try:
+        base_dir = (ctx.get("service") or {}).get("base_dir")
+        if not base_dir:
+            return False
+        event = str(
+            payload.get("hook_event_name") or payload.get("eventName") or payload.get("type") or ""
+        ).lower().replace("_", "").replace("-", "")
+        kind = "attention" if event in _WAITING_EVENTS else "complete"
+        return publish(base_dir, composed[0], composed[1], kind=kind)
+    except Exception:  # noqa: BLE001 - the caller is an agent turn
+        return False

package/src/cli.py

@@ -51,6 +51,7 @@ from .cli_commands import (
     handle_set,
     handle_stats,
     handle_status,
+    handle_tray,
     handle_unset,
     handle_update,
     handle_view,
@@ -59,6 +60,7 @@ from .cli_commands import (
     _format_bytes as _format_disk_bytes,
 )
 from .cli_helpers import _update_notice_warnings
+from .cli_hints import write_hint
 from .cli_render import (
     _format_sessions,
     _pad_table,
@@ -171,6 +173,7 @@ _COMMAND_HANDLERS = {
     "set": handle_set,
     "stats": handle_stats,
     "status": handle_status,
+    "tray": handle_tray,
     "unset": handle_unset,
     "update": handle_update,
     "view": handle_view,
@@ -257,6 +260,9 @@ def _print_help(use_color=False):
         f"  {_style('cdx doctor [--severity OK|WARN|FAIL[,OK|WARN|FAIL...]] [--check-provider-flags] [--json]', '36', use_color)}",
         f"  {_style('cdx repair [--dry-run] [--force] [--json]', '36', use_color)}",
         f"  {_style('cdx view [--json]', '36', use_color)}",
+        f"  {_style('cdx tray status [--json] [--refresh]', '36', use_color)}",
+        f"  {_style('cdx tray install|launch|uninstall|doctor [--json]', '36', use_color)}",
+        f"  {_style('cdx tray autostart [on|off|status] [--json]', '36', use_color)}",
         f"  {_style('cdx update [all] [--check] [--yes] [--json] [--version TAG]', '36', use_color)}",
         f"  {_style('cdx ready [--refresh] [--json]', '36', use_color)}",
         "",
@@ -551,6 +557,8 @@ def main(argv, options=None):
         warning_text = _update_warning_text(notices)
         if warning_text:
             out(f"{_style(warning_text, '33', use_color)}\n")
+        # Last line, after anything the user actually asked for.
+        write_hint({"env": env, "out": out, "service": service, "use_color": use_color, "update_notices": notices})
         return 0
 
     command, *rest = argv

package/src/cli_args.py

@@ -63,6 +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]"
 
 RUN_TAIL_DEFAULT_LINES = 50
 RUN_TAIL_MAX_LINES = 2000

package/src/cli_commands.py

@@ -272,5 +272,8 @@ from .commands.status import (
 from .commands.status import (
     handle_status as handle_status,
 )
+from .commands.tray import (
+    handle_tray as handle_tray,
+)
 
 

package/src/cli_hints.py

@@ -0,0 +1,167 @@
+"""One-line setup hints, shown only while they are still actionable.
+
+CDX has optional surfaces a user cannot discover by reading the output of the
+command they already run: agent alerts, and the tray companion. A hint is how
+they learn, so the bar is that it must be worth interrupting for.
+
+Four rules keep it from becoming noise, and each exists because the obvious
+version of this feature fails without it:
+
+  - Never in `--json`. That is a contract, and a helpful line inside it is a
+    parse error somewhere else.
+  - At most one per invocation, and not again for six hours. Advice that repeats
+    on every command stops being read, including the day it matters.
+  - Retired after three showings. A user who saw it three times and did not act
+    has answered; asking a fourth time is nagging, not helping.
+  - Silent on any failure. A hint is the least important thing on the screen,
+    so it never breaks, slows, or interrupts the command that carried it.
+
+Every condition is answered from local state already on disk. Nothing here
+probes a provider, touches the network, or costs a measurable amount of time.
+"""
+import json
+import os
+import time
+
+HINT_STATE_VERSION = 1
+# Long enough that a burst of commands shows nothing, short enough that a hint
+# still reaches someone who uses CDX a few times a day.
+QUIET_SECONDS = 6 * 60 * 60
+MAX_SHOWINGS = 3
+
+
+def _state_path(base_dir):
+    return os.path.join(base_dir, "hints.json")
+
+
+def _read_state(base_dir):
+    """What was shown and when. A damaged file reads as empty, never as an error."""
+    try:
+        with open(_state_path(base_dir), encoding="utf-8") as handle:
+            state = json.load(handle)
+    except (OSError, ValueError):
+        return {"version": HINT_STATE_VERSION, "hints": {}}
+    if not isinstance(state, dict) or state.get("version") != HINT_STATE_VERSION:
+        return {"version": HINT_STATE_VERSION, "hints": {}}
+    if not isinstance(state.get("hints"), dict):
+        state["hints"] = {}
+    return state
+
+
+def _write_state(base_dir, state):
+    try:
+        os.makedirs(base_dir, exist_ok=True)
+        with open(_state_path(base_dir), "w", encoding="utf-8") as handle:
+            json.dump(state, handle, indent=2)
+    except OSError:
+        # Unwritable state means hints repeat rather than disappear. That is the
+        # right way to fail: a lost preference is better than a lost command.
+        pass
+
+
+def _tray_installed(base_dir, env):
+    if (env.get("CDX_TRAY_BIN") or "").strip():
+        return True
+    try:
+        from .tray_install import read_state as read_install_state
+        return bool(read_install_state(base_dir))
+    except Exception:  # noqa: BLE001 - a hint never propagates a failure
+        return False
+
+
+def _autostart_on(env):
+    try:
+        from .tray_autostart import status as autostart_status
+        return bool(autostart_status(env=env).get("enabled"))
+    except Exception:  # noqa: BLE001
+        return False
+
+
+def _alerts_on(sessions):
+    return any(
+        session.get("notify") and session.get("enabled", True) is not False
+        for session in sessions
+    )
+
+
+def available_hints(base_dir, env, sessions):
+    """Every hint that is true right now, most useful first.
+
+    Ordered rather than scored: the tray is worth more than its autostart, and
+    both are worth more than nothing to alert about. A user with no sessions is
+    told nothing at all, because every hint here presumes there is something to
+    watch.
+    """
+    if not sessions:
+        return []
+
+    hints = []
+    installed = _tray_installed(base_dir, env)
+    if not installed:
+        hints.append((
+            "tray_not_installed",
+            "Did you know? A menu bar icon can watch your quota. Run: cdx tray install",
+        ))
+    elif not _autostart_on(env):
+        hints.append((
+            "tray_autostart_off",
+            "Did you know? The tray can start with your session. Run: cdx tray autostart on",
+        ))
+    if not _alerts_on(sessions):
+        hints.append((
+            "agent_alerts_off",
+            "Did you know? CDX can notify you when an agent finishes. Run: cdx set <name> --notify on",
+        ))
+    return hints
+
+
+def next_hint(base_dir, env, sessions, now=None):
+    """The one hint to show, or None. Records the showing when it returns one."""
+    if (env.get("CDX_NO_HINTS") or "").strip():
+        return None
+
+    now = time.time() if now is None else now
+    state = _read_state(base_dir)
+    seen = state["hints"]
+
+    # "Never shown" is its own case, not a showing at the Unix epoch. Treating
+    # the two alike silences the very first hint, which is the one that matters.
+    shown_at = [entry["last"] for entry in seen.values() if isinstance(entry, dict) and entry.get("last")]
+    if shown_at and now - max(shown_at) < QUIET_SECONDS:
+        return None
+
+    for code, message in available_hints(base_dir, env, sessions):
+        entry = seen.get(code) if isinstance(seen.get(code), dict) else {}
+        if entry.get("shown", 0) >= MAX_SHOWINGS:
+            continue
+        seen[code] = {"shown": entry.get("shown", 0) + 1, "last": now}
+        _write_state(base_dir, state)
+        return message
+    return None
+
+
+def write_hint(ctx):
+    """Print one hint after the command's own output. Never raises.
+
+    Yields to an update notice. Both want the last line, and one of them is
+    actionable news about the tool the user is running while the other is
+    optional discovery — so they never stack, and the hint waits for a quieter
+    run rather than pushing the notice up out of the eye's landing spot.
+    """
+    try:
+        if ctx.get("update_notices"):
+            return
+        env = ctx.get("env")
+        env = os.environ if env is None else env
+        service = ctx.get("service") or {}
+        base_dir = service.get("base_dir")
+        if not base_dir:
+            return
+        sessions = service["list_sessions"]()
+        message = next_hint(base_dir, env, sessions)
+        if not message:
+            return
+        from .cli_render import _dim
+        ctx["out"](f"{_dim(message, ctx.get('use_color', False))}\n")
+    except Exception:  # noqa: BLE001 - deliberate: a hint must never break a command
+        pass

package/src/commands/status.py

@@ -35,6 +35,7 @@ from ..cli_helpers import (
     _write_json,
     _write_update_notice,
 )
+from ..cli_hints import write_hint
 from ..cli_render import _dim, _info, _pad_table, _style, _warn
 from ..commands.launch import handle_launch
 from ..config import PROVIDER_CLAUDE
@@ -600,6 +601,7 @@ def handle_status(rest, ctx):
         ctx["out"](f"{_format_status_detail(row, use_color=ctx['use_color'])}\n")
         _write_refresh_warnings(refresh_errors, ctx, rows=[row])
         _write_update_notice(ctx)
+        write_hint(ctx)
         return 0
 
     rows = ctx["service"]["get_status_rows"](
@@ -619,6 +621,7 @@ def handle_status(rest, ctx):
     ctx["out"](f"{_format_status_rows(rows, use_color=ctx['use_color'], small=parsed['small'])}\n")
     _write_refresh_warnings(refresh_errors, ctx, rows=rows)
     _write_update_notice(ctx)
+    write_hint(ctx)
     return 0
 
 def _refresh_claude_auth_states(service, target_names=None, spawn_sync=None, env_override=None):