cdx-manager 0.18.4 → 0.18.6

package/src/cli_args.py

@@ -43,7 +43,7 @@ RESUME_USAGE = "Usage: cdx resume <name> [--json]"
 CAN_RESUME_USAGE = "Usage: cdx can-resume <name> [--json]"
 SELECT_USAGE = "Usage: cdx select --provider PROVIDER [--min-reasoning-effort minimal|low|medium|high|xhigh] [--min-power minimal|low|medium|high|xhigh] [--require-ready] [--refresh] --json"
 NEXT_USAGE = "Usage: cdx next [--json] [--refresh]"
-RUN_USAGE = "Usage: cdx run [session] --cwd PATH (--prompt-file PATH|--prompt TEXT|--prompt-file -) [--provider PROVIDER] [--model MODEL] [--kind assistant|code-review] [--reasoning-effort minimal|low|medium|high|xhigh] [--power minimal|low|medium|high|xhigh] [--permission review|default|auto|full|workspace-write|read-only|danger-full-access] [--timeout-seconds N] [--detach] [--failover] [--refresh] --json"
+RUN_USAGE = "Usage: cdx run [session] (--cwd|--dir) PATH (--prompt-file PATH|--prompt TEXT|--prompt-file -) [--provider PROVIDER] [--model MODEL] [--kind assistant|code-review] [--reasoning-effort minimal|low|medium|high|xhigh] [--power minimal|low|medium|high|xhigh] [--permission review|default|auto|full|workspace-write|read-only|danger-full-access] [--timeout-seconds N] [--detach] [--failover] [--refresh] --json"
 RUN_JSON_REQUIRED = "cdx run: --json is required."
 RUN_TARGET_REQUIRED = "cdx run: specify a session name or --provider PROVIDER."
 RUN_SESSION_PROVIDER_CONFLICT = "cdx run: cannot specify both a session name and --provider."
@@ -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
@@ -585,6 +585,7 @@ def _parse_run_effort(reasoning_effort, power):
 def _parse_run_args(args):
     parsed = _parse_run_flag_args(args, {
         "--cwd": {"key": "cwd", "type": "str", "default": None},
+        "--dir": {"key": "cwd", "type": "str", "default": None},
         "--prompt-file": {"key": "prompt_file", "type": "str", "default": None},
         "--prompt": {"key": "prompt", "type": "str", "default": None},
         "--provider": {"key": "provider", "type": "str", "default": None, "transform": _parse_run_provider},

package/src/commands/launch.py

@@ -28,6 +28,54 @@ from ..errors import CdxError
 from ..provider_runtime import _ensure_session_authentication, _get_auth_home, _run_interactive_provider_command
 
 
+def _parse_launch_args(args):
+    """Return the per-launch directory and ordinary launch flags."""
+    directory = None
+    cleaned = []
+    index = 0
+    while index < len(args):
+        arg = args[index]
+        if arg == "--dir":
+            if directory is not None or index + 1 >= len(args):
+                raise CdxError("Usage: cdx <name> [--dir PATH] [--resume] [--json]")
+            directory = args[index + 1]
+            index += 2
+            continue
+        if arg.startswith("--dir="):
+            if directory is not None or not arg.split("=", 1)[1]:
+                raise CdxError("Usage: cdx <name> [--dir PATH] [--resume] [--json]")
+            directory = arg.split("=", 1)[1]
+            index += 1
+            continue
+        cleaned.append(arg)
+        index += 1
+    return directory, cleaned
+
+
+def _launch_directory(session, ctx, explicit, json_flag):
+    cwd = os.path.realpath(explicit) if explicit else (ctx.get("cwd") or os.getcwd())
+    if explicit and not os.path.isdir(cwd):
+        raise CdxError(f"Invalid directory: {explicit or cwd}")
+    if explicit or json_flag or not ctx["stdin_is_tty"] or cwd not in {os.path.realpath(os.path.expanduser("~")), os.path.realpath(os.path.sep)}:
+        return cwd
+    recent = []
+    for entry in ctx["service"]["get_launch_history"](session["name"], limit=20):
+        path = entry.get("cwd")
+        if path and os.path.isdir(path) and path not in recent:
+            recent.append(path)
+    choices = recent + [cwd]
+    if len(choices) == 1:
+        return cwd
+    ctx["out"]("Choose launch directory:\n" + "".join(f"  {index + 1}. {path}\n" for index, path in enumerate(choices)))
+    answer = (ctx["options"].get("input") or input)(f"Directory [1-{len(choices)}] (default {len(choices)}): ").strip()
+    if not answer:
+        return cwd
+    try:
+        return choices[int(answer) - 1]
+    except (ValueError, IndexError):
+        raise CdxError("Launch cancelled: choose a listed directory.") from None
+
+
 def _format_resume_capability(capability, use_color=False):
     name = capability["session"]
     provider = capability["provider"]
@@ -74,12 +122,13 @@ def handle_can_resume(rest, ctx):
     return 0
 
 def handle_resume(rest, ctx):
+    directory, rest = _parse_launch_args(rest)
     json_flag, args = _parse_json_flag(rest)
     if len(args) != 1:
         raise CdxError(RESUME_USAGE)
-    return handle_launch(args[0], ctx, resume=True, force_json=json_flag)
+    return handle_launch(args[0], ctx, resume=True, force_json=json_flag, directory=directory)
 
-def handle_launch(command, ctx, initial_prompt=None, resume=False, force_json=None):
+def handle_launch(command, ctx, initial_prompt=None, resume=False, force_json=None, directory=None):
     json_flag = "--json" in ctx.get("raw_args", ctx["options"].get("raw_args", []))
     if force_json is not None:
         json_flag = force_json
@@ -91,6 +140,9 @@ def handle_launch(command, ctx, initial_prompt=None, resume=False, force_json=No
         raise CdxError(
             f"Provider {session['provider']} does not support native resume through cdx."
         )
+    cwd = _launch_directory(session, ctx, directory, json_flag)
+    if not json_flag and not ctx["stdin_is_tty"]:
+        ctx["out"](f"Using directory: {cwd}\n")
     _ensure_session_authentication(
         session,
         ctx["service"],
@@ -127,13 +179,12 @@ def handle_launch(command, ctx, initial_prompt=None, resume=False, force_json=No
             # a real turn — so it gets no instruction it does not need.
             notice += " — approve them once in Codex to enable"
         ctx["out"](f"{_info(notice, ctx['use_color'])}\n")
-    cwd = ctx.get("cwd") or os.getcwd()
     runtime_run_id = None
 
     def runtime_lifecycle(event, info):
         nonlocal runtime_run_id
         if event == "started":
-            runtime = ctx["service"]["start_session_runtime"](session["name"], info)
+            runtime = ctx["service"]["start_session_runtime"](session["name"], {**info, "cwd": cwd})
             runtime_run_id = runtime.get("runId")
         elif event == "finished" and runtime_run_id:
             ctx["service"]["finish_session_runtime"](
@@ -176,7 +227,7 @@ def handle_launch(command, ctx, initial_prompt=None, resume=False, force_json=No
         **run_info,
     })
     if json_flag:
-        extra = {"session": ctx["service"]["get_session"](session["name"])}
+        extra = {"session": ctx["service"]["get_session"](session["name"]), "cwd": cwd}
         if capability:
             extra["resume"] = capability
         _write_json(ctx, _json_success("resume" if resume else "launch", message, warnings=warnings, **extra))

package/src/commands/maintenance.py

@@ -595,11 +595,15 @@ def _align_tray_companion(ctx, target_version):
     warning, not a reason to call a good update bad.
     """
     from ..tray_install import align_companion
-    from ..tray_instance import companion_instance
 
     try:
         base_dir = ctx["service"]["base_dir"]
-        result = align_companion(base_dir, target_version, download=ctx.get("download_asset"))
+        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}"}]
 
@@ -614,21 +618,26 @@ def _align_tray_companion(ctx, target_version):
             ),
         }]
 
+    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.",
     }]
-    # A running companion keeps executing the binary it started with. Saying so
-    # beats leaving someone to wonder why the menu still looks old, and beats
-    # quitting an application they did not ask us to touch.
-    try:
-        if companion_instance(env=ctx.get("env")).get("pid"):
-            warnings.append({
-                "code": "tray_companion_restart_pending",
-                "message": "The running tray is still the previous build. Quit it from its menu and run: cdx tray launch",
-            })
-    except Exception:  # noqa: BLE001
-        pass
+    # 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
 
 
@@ -765,10 +774,12 @@ def handle_update(rest, ctx):
             current_version=current_version,
             target_version=target_version,
             mode=plan["mode"],
+            prefix=plan["prefix"],
             steps=results,
         ))
         return 0
     ctx["out"](f"{_success(message, ctx['use_color'])}\n")
+    ctx["out"](f"Install prefix: {plan['prefix']}\n")
     for warning in warnings:
         ctx["out"](f"{_warn(warning['message'], ctx['use_color'])}\n")
     return 0

package/src/commands/tray.py

@@ -5,12 +5,14 @@ and `autostart` act on recorded state and say plainly when there is none, and
 `doctor` reads all of it without changing any of it.
 """
 import os
+import shutil
 import subprocess
 from datetime import datetime, timezone
 
 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 ..config import get_cdx_home
 from ..errors import CdxError
 from ..tray_alerts import alerts_enabled, set_alerts
 from ..tray_autostart import disable as autostart_disable
@@ -42,10 +44,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.
@@ -86,9 +91,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},
@@ -103,11 +122,22 @@ 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),
+        directories=[row.get("cwd") for row in rows if row.get("active") and row.get("cwd")],
+    )
     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
@@ -210,11 +240,63 @@ def _confirm_autostart():
     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()
@@ -255,24 +337,41 @@ def _tray_install(args, ctx):
     # what people resent about desktop software. Asking keeps the reason and
     # drops the friction; a non-interactive run declines rather than deciding.
     autostart_on = False
-    autostart_reason = None
-    if parsed["no_autostart"]:
-        autostart_reason = "skipped with --no-autostart"
-    elif parsed["yes"] or (ctx["stdin_is_tty"] and not parsed["json"] and _confirm_autostart()):
+    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)
-    else:
+    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")
@@ -280,6 +379,149 @@ def _tray_install(args, ctx):
     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
 
 
@@ -352,6 +594,8 @@ def _tray_doctor(args, ctx):
     instance = companion_instance(env=env)
     desktop = desktop_capability(env=env)
     toasts = toast_capability(env=env)
+    companion_cdx = (env or {}).get("CDX_TRAY_CDX") or shutil.which("cdx", path=(env or {}).get("PATH")) or "cdx"
+    hook_store = get_cdx_home(env)
 
     checks = [
         ("companion", "installed" if state else ("override" if executable else "absent"),
@@ -369,6 +613,8 @@ def _tray_doctor(args, ctx):
         ("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"),
+        ("companion_cdx", "override" if (env or {}).get("CDX_TRAY_CDX") else "path", companion_cdx),
+        ("hook_store", "aligned" if os.path.realpath(hook_store) == os.path.realpath(base_dir) else "mismatched", hook_store),
         ("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 "-"),

package/src/session_service.py

@@ -614,6 +614,29 @@ 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
+            launch["notify_preview"] = 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 +662,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,
@@ -717,6 +740,7 @@ def start_session_runtime(store, name, payload=None):
         "pid": payload.get("pid") or os.getpid(),
         "command": payload.get("command"),
         "label": payload.get("label"),
+        "cwd": payload.get("cwd"),
         "transcriptPath": payload.get("transcript_path") or payload.get("transcriptPath"),
     }
 

package/src/session_status.py

@@ -268,6 +268,7 @@ def _status_row_from_session(store, s):
     status = s.get("lastStatus")
     enabled = s.get("enabled", True) is not False
     row_status = status if enabled else None
+    runtime = _session_runtime(store, s["name"])
     return {
         "session_name": s["name"],
         "label": s.get("label"),
@@ -279,7 +280,8 @@ def _status_row_from_session(store, s):
         # ignored `--priority` entirely.
         "priority": _row_priority(s),
         "reasoning_effort": _row_reasoning_effort(s),
-        "active": bool(_session_runtime(store, s["name"])) if enabled else False,
+        "active": bool(runtime) if enabled else False,
+        "cwd": runtime.get("cwd") if runtime else None,
         "status": "enabled" if enabled else "disabled",
         "auth_status": (s.get("auth") or {}).get("status") or "unknown",
         "auth_checked_at": _to_local_iso((s.get("auth") or {}).get("lastCheckedAt")),
@@ -313,6 +315,7 @@ def format_list_rows(store):
         "provider": s["provider"] if has_multiple else None,
         "enabled": s.get("enabled", True) is not False,
         "active": bool(_session_runtime(store, s["name"])) if s.get("enabled", True) is not False else False,
+        "cwd": (_session_runtime(store, s["name"]) or {}).get("cwd"),
         "enabled_status": "disabled" if s.get("enabled", True) is False else "enabled",
         "status": s.get("lastStatus"),
         "launch": s.get("launch") or {},

package/src/tray_contract.py

@@ -23,7 +23,7 @@ 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
@@ -223,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
@@ -254,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,
     }