cdx-manager 0.17.0 → 0.18.0

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.0-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.0-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.
 
@@ -349,8 +349,8 @@ When a session's agent finishes a turn, or stops to wait for you, cdx raises a
 desktop notification naming the session and the repository:
 
 ```text
-✓ work1     logics-manager · waiting for you
-✓ codex-a   cdx-manager · finished
+✓ work1     logics-manager · needs your attention
+✓ codex-a   cdx-manager · turn complete
 ```
 
 Off until you ask for it, per session:
@@ -359,6 +359,7 @@ Off until you ask for it, per session:
 cdx set work1 --notify on      # turn it on for one session
 cdx set --all --notify on      # turn it on everywhere
 cdx set work1 --notify off     # and back off; cdx removes what it installed
+cdx set work1 --notify-preview on  # include a short final-response preview
 ```
 
 Turning it on records the setting. The wiring happens at that session's **next
@@ -372,6 +373,16 @@ It is off by default because turning it on writes into the provider's own
 configuration and, on Codex, puts an approval prompt in front of you. That is
 not something to do to sessions you already own without being asked.
 
+Response previews are separately off by default. When enabled, a completion
+notification includes at most 180 characters of the agent's final response.
+That text can be visible on a lock screen, so enable it only for sessions whose
+output is safe to expose. Previews never read transcripts and are not shown for
+permission requests.
+
+`cdx notify` is the internal hook target, called by the provider; it is not the
+setup command. `cdx ready` is separate: it notifies you when the next cooling-
+down session becomes usable.
+
 Per platform: macOS uses `osascript`, Linux `notify-send`, Windows a toast, and
 WSL reaches the Windows notification centre through interop. On a host with no
 way to deliver one — a headless or SSH Linux session, or WSL with interop
@@ -489,7 +500,7 @@ cdx history --summary --from 2026-05-01 --to 2026-05-28
 | `cdx update [--check] [--yes] [--json] [--version TAG]` | Update cdx-manager using the installer that matches how it was installed |
 | `cdx update all [--yes] [--json]` | Check installed providers, RTK, and Ponytail across Codex profiles; show the plan and ask once before applying safe native/Homebrew updates and missing RTK/Ponytail setup |
 | `cdx ready [--refresh] [--json]` | Schedule an OS notification for the next cooling-down assistant that becomes ready, then return immediately |
-| `cdx notify` | Hook target: raises the desktop notification when a session's agent finishes a turn or waits for you. Called by the provider, not by you |
+| `cdx notify` | Internal provider hook target for agent alerts; use `cdx set <name> --notify on` to enable it |
 | `cdx next [--json] [--refresh]` | Select the best next assistant using the same priority logic as `cdx status` |
 | `cdx select --provider PROVIDER [--min-reasoning-effort minimal\|low\|medium\|high\|xhigh] [--min-power minimal\|low\|medium\|high\|xhigh] [--require-ready] [--refresh] --json` | Select a suitable session for headless automation |
 | `cdx run [session] --cwd PATH (--prompt-file PATH\|--prompt TEXT\|--prompt-file -) [--provider PROVIDER] [--model MODEL] [--reasoning-effort minimal\|low\|medium\|high\|xhigh] [--power minimal\|low\|medium\|high\|xhigh] [--permission MODE] [--timeout-seconds N] [--detach] [--failover] [--refresh] --json` | Run one headless task and return a stable JSON result; `--detach` returns the `run_id` at launch without waiting, `--failover` continues the task on the next account when this one hits its rate limit, `--prompt-file -` reads the prompt from stdin |
@@ -502,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_17_1.md

@@ -0,0 +1,29 @@
+# CDX Manager 0.17.1
+
+## Fixes
+
+### Agent-alert setup now reports provider support accurately
+
+`cdx set <name> --notify on` now distinguishes sessions where cdx can install
+provider hooks (Claude and Codex) from providers that do not expose that
+integration yet. A mixed bulk selection reports both outcomes instead of
+promising a future hook installation that cannot happen.
+
+The setting remains storable for unsupported providers, so bulk configuration
+remains predictable and a future provider integration can honour the existing
+opt-in.
+
+### Permission-request notifications constrain tool names
+
+Tool names supplied by provider hook payloads now use the same printable,
+single-line normalization as response previews and are capped at 80 characters.
+This keeps permission notifications readable and prevents malformed payloads
+from expanding or controlling desktop notification text.
+
+## Validation
+
+- `npm run lint`
+- `npm test`
+- `npm run release:validate`
+- `logics-manager lint --require-status`
+- `logics-manager audit --legacy-cutoff-version 1.1.0 --group-by-doc`

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/checksums/release-archives.json

@@ -184,6 +184,14 @@
     "v0.16.0": {
       "github_tarball_sha256": "bdcd2808922410b20567ba86589d49166c5c2b9404325195b28457df80ca3dad",
       "github_zip_sha256": "e89cb8c964304f0805d06da9d355d543f8a590e0febbf07e585a692ccf73ef99"
+    },
+    "v0.17.0": {
+      "github_tarball_sha256": "6f321106aa426590ce809788fab4f26401b4cc499a6c518a56a4f24f8bfb6c2e",
+      "github_zip_sha256": "72665a0006df40bb27301140b0ed6600a0d91b456facbb5a2aad2a917357ae75"
+    },
+    "v0.17.1": {
+      "github_tarball_sha256": "f1cc36d55f17d8e5c8ad0b0ebc419e812b8788742c3e45ce1137303924114dd7",
+      "github_zip_sha256": "29acb306ad76535d0db701504a53b9887b8a6b0b95d968634139f85952a34ec3"
     }
   }
 }

package/package.json

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

package/src/agent_notify.py

@@ -15,17 +15,26 @@ 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"
 ENABLED_ENV = "CDX_NOTIFY"
+PREVIEW_ENV = "CDX_NOTIFY_PREVIEW"
 
 # Our entries are recognised by the command they run, not by a marker key of our
 # own: both providers validate this file against their own schema, and an extra
 # key they do not know is a rejection risk for no gain.
 HOOK_ARG = "notify"
 
-_WAITING_EVENTS = {"notification", "permissionrequest", "userpromptsubmit"}
+_WAITING_EVENTS = {"notification", "permissionrequest"}
+_PREVIEW_LIMIT = 180
+_TOOL_NAME_LIMIT = 80
+
+
+def supports_agent_alerts(provider):
+    """Whether cdx can provision provider hooks for this session."""
+    return provider in {"claude", "codex"}
 
 
 def resolve_hook_command(env=None):
@@ -70,9 +79,29 @@ def compose_notification(payload, env=None, cwd=None):
         return None
     directory = payload.get("cwd") or payload.get("workspace") or cwd or os.getcwd()
     event = str(payload.get("hook_event_name") or payload.get("eventName") or payload.get("type") or "").lower()
-    state = "waiting for you" if event.replace("_", "") in _WAITING_EVENTS else "finished"
+    event = event.replace("_", "").replace("-", "")
+    state = "needs your attention" if event in _WAITING_EVENTS else "turn complete"
+    tool_name = _notification_text(payload.get("tool_name"), _TOOL_NAME_LIMIT)
+    if event == "permissionrequest" and tool_name:
+        state += f" ({tool_name})"
     where = os.path.basename(str(directory).rstrip("/\\")) or directory
-    return f"✓ {session}", f"{where} · {state}"
+    preview = _notification_preview(payload, event, env)
+    return f"✓ {session}", f"{where} · {state}" + (f" — {preview}" if preview else "")
+
+
+def _notification_preview(payload, event, env):
+    if event != "stop" or env.get(PREVIEW_ENV) != "1":
+        return ""
+    return _notification_text(payload.get("last_assistant_message"), _PREVIEW_LIMIT)
+
+
+def _notification_text(value, limit):
+    if not isinstance(value, str):
+        return ""
+    value = " ".join("".join(char if char.isprintable() else " " for char in value).split())
+    if len(value) <= limit:
+        return value
+    return value[:limit - 1].rstrip() + "…"
 
 
 def handle_notify(rest, ctx):
@@ -82,12 +111,22 @@ def handle_notify(rest, ctx):
         stdin_text = None
         # "stdin" in ctx is the {"isTTY": ...} descriptor, not a stream.
         reader = ctx.get("prompt_stdin") or sys.stdin
+        env = os.environ if ctx.get("env") is None else ctx["env"]
+        if ctx.get("stdin_is_tty") and not env.get(SESSION_ENV):
+            ctx["out"]("cdx notify is called by provider hooks. Enable agent alerts with: cdx set <name> --notify on\n")
+            return 0
         if reader is not None and not ctx.get("stdin_is_tty"):
             stdin_text = reader.read()
-        env = os.environ if ctx.get("env") is None else ctx["env"]
-        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
@@ -98,6 +137,8 @@ def launch_notify_env(session, enabled, env=None):
     values = {SESSION_ENV: session["name"]}
     if not enabled:
         values[ENABLED_ENV] = "0"
+    elif (session.get("launch") or {}).get("notify_preview") is True:
+        values[PREVIEW_ENV] = "1"
     return values
 
 
@@ -130,6 +171,8 @@ def provision(auth_home, provider, enabled, env=None, spawn_sync=None, base_dir=
         # Nothing could be delivered on this host, so installing a hook would only
         # buy the user an approval prompt for a feature that shows nothing.
         enabled = False
+    if not supports_agent_alerts(provider):
+        return False
     command = resolve_hook_command(env)
     if provider == "claude":
         return _apply_hooks(hook_config_path(auth_home, provider), enabled, command)
@@ -224,7 +267,7 @@ def _write_codex_plugin(auth_home, command, base_dir=None):
         os.path.join(root, "hooks", "cdx-hooks.json"): {
             "hooks": {
                 event: [{"hooks": [{"type": "command", "command": f"{command} {HOOK_ARG}"}]}]
-                for event in ("Stop", "Notification")
+                for event in ("Stop", "PermissionRequest")
             },
         },
     }
@@ -322,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,
@@ -231,8 +234,8 @@ def _print_help(use_color=False):
         f"  {_style('cdx config <name> [--json]', '36', use_color)}",
         f"  {_style('cdx configs [--json]', '36', use_color)}",
         f"  {_style('cdx power|perm|fast|model <name|all|provider:PROVIDER|a,b> <value|default> [--json]', '36', use_color)}",
-        f"  {_style('cdx set <name>|--sessions all|a,b|--provider PROVIDER [--power minimal|low|medium|high|xhigh] [--permission review|default|auto|full] [--fast on|off] [--rtk on|off] [--logics on|off] [--model MODEL] [--priority 0..100] [--json]', '36', use_color)}",
-        f"  {_style('cdx unset <name>|--sessions all|a,b|--provider PROVIDER (--power|--permission|--fast|--rtk|--logics|--model|--priority|--all) [--json]', '36', use_color)}",
+        f"  {_style('cdx set <name>|--sessions all|a,b|--provider PROVIDER [--power minimal|low|medium|high|xhigh] [--permission review|default|auto|full] [--fast on|off] [--rtk on|off] [--logics on|off] [--notify on|off] [--notify-preview on|off] [--model MODEL] [--priority 0..100] [--json]', '36', use_color)}",
+        f"  {_style('cdx unset <name>|--sessions all|a,b|--provider PROVIDER (--power|--permission|--fast|--rtk|--logics|--notify|--notify-preview|--model|--priority|--all) [--json]', '36', use_color)}",
         f"  {_style('cdx history [name] [--limit N] [--summary] [--since 7d|today|DATE] [--from DATE] [--to DATE] [--json]', '36', use_color)}",
         f"  {_style('cdx stats [name] [--since 7d|today|DATE] [--from DATE] [--to DATE] [--json]', '36', use_color)}",
         f"  {_style('cdx last [--json]', '36', use_color)}",
@@ -257,9 +260,15 @@ 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)}",
-        f"  {_style('cdx notify', '36', use_color)}  # hook target, called by the provider",
+        "",
+        _style("Notifications:", "1", use_color),
+        f"  {_style('cdx set <name> --notify on', '36', use_color)}  # agent finishes or needs attention",
+        f"  {_style('cdx ready', '36', use_color)}  # next session to become ready",
         f"  {_style('cdx <name> [--json]', '36', use_color)}",
         f"  {_style('cdx --help', '36', use_color)}",
         f"  {_style('cdx --version', '36', use_color)}",
@@ -548,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
@@ -249,6 +250,7 @@ def _parse_set_args(args):
         "--rtk": {"key": "rtk", "type": "str", "default": None, "transform": _parse_fast_value},
         "--logics": {"key": "logics", "type": "str", "default": None, "transform": _parse_fast_value},
         "--notify": {"key": "notify", "type": "str", "default": None, "transform": _parse_fast_value},
+        "--notify-preview": {"key": "notify_preview", "type": "str", "default": None, "transform": _parse_fast_value},
         "--model": {"key": "model", "type": "str", "default": None},
         "--fallback-model": {"key": "fallback_model", "type": "str", "default": None},
         "--budget": {"key": "budget", "type": "str", "default": None, "transform": _parse_budget_value},
@@ -270,7 +272,7 @@ def _parse_set_args(args):
         raise CdxError(SET_USAGE)
     settings = {
         key: parsed[key]
-        for key in ("power", "permission", "fast", "rtk", "logics", "notify", "model", "fallback_model", "budget", "extra_args", "priority")
+        for key in ("power", "permission", "fast", "rtk", "logics", "notify", "notify_preview", "model", "fallback_model", "budget", "extra_args", "priority")
         if parsed[key] is not None
     }
     if not settings:
@@ -293,6 +295,7 @@ def _parse_unset_args(args):
         "--rtk": {"key": "rtk", "type": "bool", "default": False},
         "--logics": {"key": "logics", "type": "bool", "default": False},
         "--notify": {"key": "notify", "type": "bool", "default": False},
+        "--notify-preview": {"key": "notify_preview", "type": "bool", "default": False},
         "--model": {"key": "model", "type": "bool", "default": False},
         "--fallback-model": {"key": "fallback_model", "type": "bool", "default": False},
         "--budget": {"key": "budget", "type": "bool", "default": False},
@@ -314,7 +317,7 @@ def _parse_unset_args(args):
     if not parsed["names"] and not parsed["sessions"] and not parsed["provider"]:
         raise CdxError(UNSET_USAGE)
     _UNSET_KEYS = (
-        "power", "reasoning_effort", "permission", "fast", "rtk", "logics", "notify",
+        "power", "reasoning_effort", "permission", "fast", "rtk", "logics", "notify", "notify_preview",
         "model", "fallback_model", "budget", "extra_args", "priority",
     )
     keys = list(_UNSET_KEYS) if parsed["all"] else [key for key in _UNSET_KEYS if parsed[key]]

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_helpers.py

@@ -486,7 +486,8 @@ def _format_launch_config(session, use_color=False):
         ("fast", "Fast"),
         ("rtk", "RTK"),
         ("logics", "Logics"),
-        ("notify", "Notify"),
+        ("notify", "Agent alerts"),
+        ("notify_preview", "Response preview"),
         ("model", "Model"),
         ("fallback_model", "Fallback"),
         ("budget", "Budget"),
@@ -509,18 +510,18 @@ def _format_launch_config(session, use_color=False):
 def _format_launch_settings_hint(name="<name>"):
     return (
         f"Set a value: cdx set {name} --power medium --permission auto "
-        "--fast on --rtk on --logics on --notify on --model MODEL --priority 80"
+        "--fast on --rtk on --logics on --notify on --notify-preview on --model MODEL --priority 80"
     )
 
 def _format_launch_setting_value(launch, key, use_color=False):
-    if key in ("fast", "rtk", "logics", "notify"):
+    if key in ("fast", "rtk", "logics", "notify", "notify_preview"):
         if launch.get(key) is True:
             return _style("on", "32", use_color)
         if launch.get(key) is False:
             return _style("off", "2", use_color)
         if key == "logics":
             return _dim("auto", use_color)
-        if key == "notify":
+        if key in ("notify", "notify_preview"):
             return _style("off", "2", use_color)
         return _dim("default", use_color)
     value = launch.get(key)