cdx-manager 0.18.3 → 0.18.5

package/src/cli.py

@@ -84,7 +84,7 @@ from .status_view import (
 from .update_check import check_for_update, check_logics_manager_for_update
 
 
-def _resolve_version():
+def _resolve_version(package_root=None, metadata_lookup=None):
     """The version, resolved rather than restated.
 
     This was a hardcoded string, a fourth copy alongside VERSION, package.json,
@@ -95,23 +95,38 @@ def _resolve_version():
     happens in a checkout, where it is the thing being edited and the installed
     metadata is whatever was last `pip install`ed. Installed packages have no
     such file and fall through to their own metadata.
+
+    An npm install has neither: no Python distribution metadata, and — until
+    VERSION was added to the published `files` list — no VERSION either. That
+    combination reported 0.0.0, which reads as permanently out of date and makes
+    `cdx update` succeed without ever silencing itself. package.json ships in
+    every npm tarball by construction, so reading it is the branch that cannot
+    go missing again.
     """
-    version_file = os.path.join(
-        os.path.dirname(os.path.dirname(os.path.abspath(__file__))), "VERSION"
-    )
+    if package_root is None:
+        package_root = os.path.dirname(os.path.dirname(os.path.abspath(__file__)))
     try:
-        with open(version_file, encoding="utf-8") as handle:
+        with open(os.path.join(package_root, "VERSION"), encoding="utf-8") as handle:
             text = handle.read().strip()
         if text:
             return text
     except OSError:
         pass
     try:
-        from importlib.metadata import version
+        if metadata_lookup is None:
+            from importlib.metadata import version as metadata_lookup
 
-        return version("cdx-manager")
-    except Exception:  # noqa: BLE001 - any resolution failure falls back below
-        return "0.0.0"
+        return metadata_lookup("cdx-manager")
+    except Exception:  # noqa: BLE001 - not installed as a Python distribution
+        pass
+    try:
+        with open(os.path.join(package_root, "package.json"), encoding="utf-8") as handle:
+            text = str(json.load(handle).get("version") or "").strip()
+        if text:
+            return text
+    except (OSError, ValueError):
+        pass
+    return "0.0.0"
 
 
 VERSION = _resolve_version()

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] | cdx tray alerts [on|off|status] [--json]"
+TRAY_USAGE = "Usage: cdx tray status [--json] [--refresh] [--beat] | cdx tray install [--json] [--yes] [--autostart|--no-autostart] [--alerts|--no-alerts] | cdx tray 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] | cdx tray plugin [status|enable <name>|disable <name>|run <action>] [--json] | cdx tray terminal [status|set <app>|clear] [--json]"
 
 RUN_TAIL_DEFAULT_LINES = 50
 RUN_TAIL_MAX_LINES = 2000

package/src/commands/maintenance.py

@@ -587,6 +587,60 @@ 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
+
+    try:
+        base_dir = ctx["service"]["base_dir"]
+        result = align_companion(
+            base_dir, target_version,
+            download=ctx.get("download_asset"),
+            env=ctx.get("env"),
+            spawn=ctx.get("spawn_detached"),
+        )
+    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"
+            ),
+        }]
+
+    if result.get("restarted"):
+        return [{
+            "code": "tray_companion_updated",
+            "message": f"Updated the tray companion to {target_version} and restarted it.",
+        }]
+
+    warnings = [{
+        "code": "tray_companion_updated",
+        "message": f"Updated the tray companion to {target_version} as well.",
+    }]
+    # It was replaced but is not running. Only worth saying when there was one
+    # to bring back: a user who had no tray open did not lose anything.
+    if result.get("restart_reason") and result.get("restart_reason") != "no tray was running":
+        warnings.append({
+            "code": "tray_companion_restart_pending",
+            "message": (
+                f"The tray companion did not restart: {result['restart_reason']} "
+                "Run: cdx tray launch"
+            ),
+        })
+    return warnings
+
+
 def handle_update(rest, ctx):
     parsed = _parse_update_args(rest)
     if parsed["all"]:
@@ -704,6 +758,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

@@ -27,6 +27,7 @@ from ..tray_events import (
     acknowledge as ack_events,
 )
 from ..tray_events import (
+    events_path,
     read_events,
     write_heartbeat,
 )
@@ -41,10 +42,13 @@ from ..tray_install import (
     uninstall,
 )
 from ..tray_instance import companion_instance
+from ..tray_plugins import ADAPTERS, collect_cards, enabled_plugins, set_plugin_enabled
+from ..tray_terminal import REFUSAL as TERMINAL_REFUSAL
+from ..tray_terminal import clear_terminal, set_terminal, terminal_preference
 
 TRAY_ACTIONS = (
     "status", "install", "launch", "uninstall", "autostart", "doctor",
-    "events", "ack", "heartbeat", "alerts",
+    "events", "ack", "heartbeat", "alerts", "plugin", "terminal",
 )
 
 # Codes rather than prose, so a caller can branch on them.
@@ -85,9 +89,23 @@ def handle_tray(rest, ctx):
         return _tray_heartbeat(args, ctx)
     if action == "alerts":
         return _tray_alerts(args, ctx)
+    if action == "plugin":
+        return _tray_plugin(args, ctx)
+    if action == "terminal":
+        return _tray_terminal(args, ctx)
     return _tray_install(args, ctx)
 
 
+def _plugin_cache(ctx):
+    """The per-process card cache.
+
+    `cdx tray status` is a fresh process per poll, so this only helps within one
+    invocation today. It exists as the seam the TTL is honoured through, and the
+    place a longer-lived cache would go without every adapter learning about it.
+    """
+    return ctx.setdefault("plugin_cache", {})
+
+
 def _tray_status(args, ctx):
     parsed = _parse_flag_args(args, {
         "--json": {"key": "json", "type": "bool", "default": False},
@@ -102,11 +120,21 @@ def _tray_status(args, ctx):
         force_refresh=parsed["refresh"],
         cache_only=not parsed["refresh"],
     )
+    # Enabled integrations contribute a card each. A manual refresh passes no
+    # cache, so it is what actually re-asks them; a poll reuses a card for its
+    # TTL and does not make an integration pay the tray's rate.
+    cards = collect_cards(
+        ctx["service"]["base_dir"],
+        env=ctx.get("env"),
+        cache=None if parsed["refresh"] else _plugin_cache(ctx),
+    )
     snapshot = build_snapshot(
         rows,
         datetime.now(timezone.utc),
         ctx["version"],
         refreshable=not any(row.get("active") for row in rows),
+        plugins=cards,
+        terminal=terminal_preference(ctx["service"]["base_dir"]),
     )
     # Pending alerts ride along with the snapshot rather than costing their own
     # call. Across WSL every invocation is a `wsl.exe` crossing measured at
@@ -116,6 +144,11 @@ def _tray_status(args, ctx):
     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.
@@ -199,10 +232,70 @@ 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 _confirm_alerts():
+    answer = input("Notify you when an agent finishes a turn or waits for you? [Y/n] ")
+    return answer.strip().lower() in ("", "y", "yes")
+
+
+def _accepted(parsed, ctx, on_flag, off_flag, confirm):
+    """One consent, resolved the same way for each question.
+
+    Two rules make it predictable. An explicit flag always wins, so a script
+    gets what it asked for and never a prompt. And in the absence of one, only
+    an interactive human-readable run asks — a piped or `--json` invocation
+    declines rather than deciding on someone's behalf.
+    """
+    if parsed[off_flag]:
+        return False, f"skipped with --{off_flag.replace('_', '-')}"
+    if parsed[on_flag] or parsed["yes"]:
+        return True, None
+    if ctx["stdin_is_tty"] and not parsed["json"] and confirm():
+        return True, None
+    return False, None
+
+
+def _enable_alerts_everywhere(ctx):
+    """Turn alerts on for every session that can have them, and for future ones.
+
+    The two halves are one promise: a user who accepted alerts means the tray
+    tells them when an agent needs them, not that it does so for the sessions
+    that happened to exist at the moment they answered.
+
+    Providers with no hook mechanism are left alone rather than written to with
+    a setting they will ignore.
+    """
+    from ..agent_notify import supports_agent_alerts
+    from ..tray_defaults import set_alerts_default
+
+    service = ctx["service"]
+    set_alerts_default(service["base_dir"], True)
+    enabled, codex = [], False
+    for session in service["list_sessions"]():
+        if not supports_agent_alerts(session["provider"]):
+            continue
+        if (session.get("launch") or {}).get("notify") is True:
+            continue
+        service["set_launch_settings"](session["name"], {"notify": True})
+        enabled.append(session["name"])
+        codex = codex or session["provider"] == "codex"
+    return {"sessions": enabled, "codex_trust_required": codex}
+
+
 def _tray_install(args, ctx):
     parsed = _parse_flag_args(args, {
         "--json": {"key": "json", "type": "bool", "default": False},
+        "--yes": {"key": "yes", "type": "bool", "default": False},
+        "--autostart": {"key": "autostart", "type": "bool", "default": False},
+        "--no-autostart": {"key": "no_autostart", "type": "bool", "default": False},
+        "--alerts": {"key": "alerts", "type": "bool", "default": False},
+        "--no-alerts": {"key": "no_alerts", "type": "bool", "default": False},
     }, TRAY_USAGE, positionals_key="args", max_positionals=0)
+    env = ctx.get("env")
     target = current_target()
     if not target:
         return _refuse(
@@ -222,14 +315,210 @@ 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
+    wanted, autostart_reason = _accepted(parsed, ctx, "autostart", "no_autostart", _confirm_autostart)
+    if wanted:
+        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)
+    elif autostart_reason is None:
+        autostart_reason = "not enabled; run: cdx tray autostart on"
+
+    # The second question, asked separately because it is a different decision
+    # with a different cost: one adds a login item, the other writes hooks into
+    # each provider's own configuration.
+    alerts_on = False
+    alerts_reason = None
+    alerts_result = {"sessions": [], "codex_trust_required": False}
+    wanted, alerts_reason = _accepted(parsed, ctx, "alerts", "no_alerts", _confirm_alerts)
+    if wanted:
+        try:
+            alerts_result = _enable_alerts_everywhere(ctx)
+            alerts_on = True
+        except Exception as error:  # noqa: BLE001 - the install itself succeeded
+            alerts_reason = str(error)
+    elif alerts_reason is None:
+        alerts_reason = "not enabled; run: cdx set --all --notify 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,
+            alerts=alerts_on,
+            alerts_sessions=alerts_result["sessions"],
+            codex_trust_required=alerts_result["codex_trust_required"],
         ))
         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"
+    )
+    if alerts_on:
+        count = len(alerts_result["sessions"])
+        covered = f"{count} session(s)" if count else "no existing session"
+        ctx["out"](
+            f"Agent alerts: on for {covered}, and for new ones — "
+            "hooks install at each session's next launch.\n"
+        )
+        if alerts_result["codex_trust_required"]:
+            # Said here rather than discovered later: Codex puts an approval
+            # prompt in front of the user at the next launch, and cdx will not
+            # write that trust on their behalf.
+            ctx["out"]("Codex will ask you once to approve the cdx hook plugin.\n")
+    else:
+        ctx["out"](f"Agent alerts: {alerts_reason}\n")
+    return 0
+
+
+PLUGIN_UNKNOWN = "tray_plugin_unknown"
+TERMINAL_INVALID = "tray_terminal_invalid"
+
+
+def _tray_terminal(args, ctx):
+    """Choose the terminal a session row opens, or go back to the default.
+
+    A refusal is a refusal, not a silent normalisation: a value that cannot be
+    stored says why, and nothing is written. Storing a sanitized version of what
+    someone typed would make the rule invisible exactly where it matters.
+    """
+    parsed = _parse_flag_args(args, {
+        "--json": {"key": "json", "type": "bool", "default": False},
+    }, TRAY_USAGE, positionals_key="args", max_positionals=2)
+    positional = parsed["args"] or ["status"]
+    mode = positional[0]
+    base_dir = ctx["service"]["base_dir"]
+
+    if mode == "clear":
+        clear_terminal(base_dir)
+    elif mode == "set":
+        if len(positional) < 2:
+            raise CdxError(TRAY_USAGE)
+        try:
+            set_terminal(base_dir, positional[1])
+        except ValueError:
+            return _refuse(ctx, parsed["json"], "tray.terminal", TERMINAL_INVALID, TERMINAL_REFUSAL)
+    elif mode != "status":
+        raise CdxError(TRAY_USAGE)
+
+    chosen = terminal_preference(base_dir)
+    message = (
+        f"Tray session rows open {chosen}." if chosen
+        else "Tray session rows open this platform's default terminal."
+    )
+    if parsed["json"]:
+        _write_json(ctx, _json_success(
+            "tray.terminal", message, terminal=chosen, applied=mode in ("set", "clear"),
+        ))
+        return 0
+    ctx["out"](f"{message}\n")
+    if chosen:
+        # Said once, at the moment it is chosen: the companion falls back
+        # silently, and a user whose terminal never opens should know that is
+        # the designed behaviour rather than a broken setting.
+        ctx["out"](f"{_dim('If it is not installed, the platform default opens instead.', ctx['use_color'])}\n")
+    return 0
+
+
+def _tray_plugin(args, ctx):
+    """Turn an integration on or off, and say what is on.
+
+    Explicit in both directions and reversible, because an integration runs
+    another tool's command on the user's behalf: nothing here has a default that
+    turns something on, and `disable` is not a hidden setting.
+    """
+    parsed = _parse_flag_args(args, {
+        "--json": {"key": "json", "type": "bool", "default": False},
+    }, TRAY_USAGE, positionals_key="args", max_positionals=2)
+    positional = parsed["args"] or ["status"]
+    mode = positional[0]
+    if mode not in ("enable", "disable", "status", "run"):
+        raise CdxError(TRAY_USAGE)
+    base_dir = ctx["service"]["base_dir"]
+
+    if mode == "run":
+        return _tray_plugin_run(positional[1:], parsed, ctx)
+
+    if mode in ("enable", "disable"):
+        if len(positional) < 2:
+            raise CdxError(TRAY_USAGE)
+        name = positional[1]
+        if name not in ADAPTERS:
+            return _refuse(
+                ctx, parsed["json"], "tray.plugin", PLUGIN_UNKNOWN,
+                f"No tray integration is called {name}. Known: {', '.join(sorted(ADAPTERS))}.",
+            )
+        set_plugin_enabled(base_dir, name, mode == "enable")
+
+    enabled = enabled_plugins(base_dir)
+    available = _available_plugins(ctx, enabled)
+    message = (
+        f"Tray integrations enabled: {', '.join(enabled)}" if enabled
+        else "No tray integration is enabled."
+    )
+    if parsed["json"]:
+        _write_json(ctx, _json_success(
+            "tray.plugin", message, enabled=enabled, known=sorted(ADAPTERS),
+            activatable=available, applied=mode in ("enable", "disable"),
+        ))
+        return 0
+    ctx["out"](f"{message}\n")
+    for name in available:
+        # Said once, as an offer rather than a nudge repeated on every command:
+        # the tool is here, the card is not on, and this is how to turn it on.
+        ctx["out"](f"{_dim(f'{name} is installed but not enabled. Run: cdx tray plugin enable {name}', ctx['use_color'])}\n")
+    return 0
+
+
+def _available_plugins(ctx, enabled):
+    """Integrations whose tool is installed and whose card is not enabled."""
+    from ..logics_view import resolve_logics_manager
+
+    if "logics" in enabled or not resolve_logics_manager(ctx.get("env") or {}):
+        return []
+    return ["logics"]
+
+
+def _tray_plugin_run(rest, parsed, ctx):
+    """Perform one card action, named by its id.
+
+    The tray sends an id back rather than a command, and this is where that
+    matters: the id is matched against what CDX knows how to do, and anything
+    else is refused. There is no path from a card to a shell.
+    """
+    from ..tray_plugin_actions import perform_action
+
+    if not rest:
+        raise CdxError(TRAY_USAGE)
+    result = perform_action(rest[0], ctx)
+    if not result["ok"]:
+        return _refuse(ctx, parsed["json"], "tray.plugin.run", result["code"], result["message"])
+    if parsed["json"]:
+        _write_json(ctx, _json_success("tray.plugin.run", result["message"], applied=True))
+        return 0
+    ctx["out"](f"{result['message']}\n")
     return 0
 
 
@@ -308,7 +597,12 @@ 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"),

package/src/session_service.py

@@ -614,6 +614,28 @@ def rename_session(base_dir, store, source_name, dest_name):
     return result["session"]
 
 
+def _launch_defaults_for(base_dir, provider):
+    """The launch settings a new session starts with.
+
+    Agent alerts are the one setting that can be inherited, and only from an
+    explicit answer given during `cdx tray install`. Without this, accepting
+    alerts once covered the sessions that existed at that moment and silently
+    excluded every session created afterwards.
+    """
+    from .agent_notify import supports_agent_alerts
+    from .tray_defaults import alerts_default
+
+    launch = dict(DEFAULT_LAUNCH_SETTINGS)
+    try:
+        if supports_agent_alerts(provider) and alerts_default(base_dir):
+            launch["notify"] = True
+    except OSError:
+        # An unreadable default is no default. Creating the session matters
+        # more than inheriting a preference.
+        pass
+    return launch
+
+
 def create_session(base_dir, env, store, name, provider=DEFAULT_PROVIDER):
     _validate_new_session_name(name)
     normalized_provider = _normalize_provider(provider)
@@ -639,7 +661,7 @@ def create_session(base_dir, env, store, name, provider=DEFAULT_PROVIDER):
         "lastLaunchedAt": None,
         "lastStatusAt": None,
         "lastStatus": None,
-        "launch": dict(DEFAULT_LAUNCH_SETTINGS),
+        "launch": _launch_defaults_for(base_dir, normalized_provider),
         "auth": {
             "status": "unknown",
             "lastCheckedAt": None,

package/src/tray_contract.py

@@ -19,10 +19,11 @@ 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
-SCHEMA_MINOR = 0
+SCHEMA_MINOR = 2
 
 # Below this much remaining capacity a session cannot usefully take work. Shared
 # with the ranking's own usability threshold so the tray and `cdx next` do not
@@ -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,
@@ -196,7 +223,7 @@ def tooltip_for(worst):
     return "CDX · " + " · ".join(parts)
 
 
-def build_snapshot(rows, now, cdx_version, refreshable=True):
+def build_snapshot(rows, now, cdx_version, refreshable=True, plugins=None, terminal=None):
     """The whole contract, from the rows `cdx status` already returns.
 
     `icon` carries no session name, account, or figure: it is what shows while
@@ -227,6 +254,15 @@ def build_snapshot(rows, now, cdx_version, refreshable=True):
         "sessions": sessions,
         "refreshable": bool(refreshable),
         "actions": ["refresh", "open_terminal"],
+        # Zero or more bounded cards from enabled integrations. A minor-version
+        # addition: a companion that predates it ignores the key and shows
+        # exactly what it showed before.
+        "plugins": list(plugins or []),
+        # Which terminal a session row should open, or None for the platform's
+        # own. Carried here rather than kept by the companion, because every
+        # other durable tray preference already lives in CDX and a second store
+        # is a second thing to keep in step.
+        "terminal": terminal,
     }
 
 

package/src/tray_defaults.py

@@ -0,0 +1,48 @@
+"""What a newly created session inherits, once the user has said yes once.
+
+Accepting agent alerts during `cdx tray install` has to mean two different
+things, and only saying one of them is what made the feature feel broken: the
+sessions that exist today get alerts, and the ones created tomorrow get them
+too. Without the second, a user who accepted alerts finds their next session
+silent and has no reason to suspect a per-session opt-in they never saw.
+
+Stored beside the mute state rather than in the session file, because it is not
+a property of any session: it is the answer to a question asked once, and a
+session created later has to be able to read it.
+"""
+import json
+import os
+
+STATE_VERSION = 1
+
+
+def state_path(base_dir):
+    return os.path.join(base_dir, "tray", "defaults.json")
+
+
+def alerts_default(base_dir):
+    """Whether a new supported session starts with alerts on.
+
+    Off unless explicitly accepted. Anything unreadable, unrecognised or from a
+    version this build does not know reads as off: inheriting an opt-in from a
+    file we cannot understand would enable provider hooks nobody agreed to.
+    """
+    try:
+        with open(state_path(base_dir), encoding="utf-8") as handle:
+            state = json.load(handle)
+    except (OSError, ValueError):
+        return False
+    if not isinstance(state, dict) or state.get("version") != STATE_VERSION:
+        return False
+    return state.get("notify") is True
+
+
+def set_alerts_default(base_dir, enabled):
+    """Record the answer, 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, "notify": bool(enabled)}, handle, indent=2)
+    os.replace(temp, path)
+    return bool(enabled)