cdx-manager 0.18.6 → 0.19.1

package/README.md

@@ -4,7 +4,7 @@
 
 <br clear="left"/>
 
-[![License](https://img.shields.io/badge/license-MIT-4C8BF5)](LICENSE) ![Version](https://img.shields.io/badge/version-v0.18.6-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.19.1-4C8BF5) ![Python](https://img.shields.io/badge/python-3.9%2B-3776AB?logo=python&logoColor=white)
 
 **Stop guessing which AI account still has quota.** `cdx` tracks the rate-limit window of every Codex and Claude account you own, tells you which one is usable right now, and launches it with isolated auth — in one command.
 
@@ -74,7 +74,7 @@ The reason `cdx` exists: knowing, across every account you own, which one you ca
 
 - **Usage at a glance.** `cdx status` shows token usage, 5-hour window quota, weekly quota, last-updated timestamps, priority guidance, and the last launched session in one aligned table.
 - **Pick for me.** `cdx next` selects the best available assistant from your pinned priorities and the live quota picture, shows the reason, and prints the exact command to run.
-- **Agent notifications.** When a session finishes a turn or blocks waiting for you, cdx raises a desktop notification naming the session and the repository — so you can run several in parallel without watching any of them. Opt in per session with `cdx set <name> --notify on`.
+- **Agent notifications.** At the first interactive launch of a supported provider, cdx asks before installing its hook. Delivery starts muted; `cdx tray alerts on` enables the next event globally, with or without the tray running.
 - **Next-ready notification.** `cdx ready` schedules a native system notification for the next assistant that comes back from cooldown, then returns immediately.
 - **Passive status resolution.** Codex status is read from the local Codex app-server rate-limit API when available, with legacy transcript/history parsing kept as a fallback.
 - **Banked reset visibility.** Eligible Codex accounts show the number of manually redeemable bonus resets in `cdx status` and expose reset details in JSON output.
@@ -114,8 +114,6 @@ The reason `cdx` exists: knowing, across every account you own, which one you ca
 - **Launch history.** Inspect recent launches with provider, result, duration, working directory, launch settings, and transcript path.
 - **Aggregate usage.** `cdx stats` totals runs, token usage, and time spent per session over any period.
 
-![cdx stats: runs, input and output tokens, total time and last use per session](docs/assets/stats.png)
-
 - **Disk usage and cleanup.** `cdx disk` reports `CDX_HOME` usage, `cdx disk profiles --candidates` identifies reclaimable profile caches/logs with evidence, and `cdx clean profiles ...` applies explicit cleanup actions.
 - **Health and repair.** `cdx doctor` inspects dependencies, permissions, and orphan profiles; `cdx repair` plans or applies safe fixes.
 - **Portable bundles.** `cdx export` / `cdx import` move sessions between machines, with passphrase-encrypted auth data when you ask for it.
@@ -357,7 +355,7 @@ desktop notification naming the session and the repository:
 ✓ codex-a   cdx-manager · turn complete
 ```
 
-Off until you ask for it, per session:
+CDX asks once at the first eligible interactive launch before writing a provider hook. Consent is installation-wide, but each profile receives its hook only when it is next launched. Alert delivery then starts muted; use `cdx tray alerts on` when you want banners. The older per-session commands remain compatible:
 
 ```bash
 cdx set work1 --notify on      # turn it on for one session
@@ -466,6 +464,8 @@ Interactive launches and resumes set the terminal window title to `session — f
 
 The title is only written when stdout is a terminal. Nothing is emitted for `--json` launches, redirected or piped output, `cdx run` and other headless runs, login flows, or Ollama sessions. Session names and directories are stripped of escape and control characters before the title is emitted, and cdx does not restore the previous title when the session ends.
 
+Claude Code writes its own animated title while an action runs, and it redraws far more often than cdx re-asserts the shared title. So interactive Claude launches and resumes started by cdx set the Claude-specific `CLAUDE_CODE_DISABLE_TERMINAL_TITLE=1` in the provider environment, which stops Claude from setting and clearing the title and leaves `session — folder` stable while Claude is busy. Claude's in-TUI activity indicator is unaffected, the value is forced so an ambient setting in your shell cannot hand the title back, and headless `cdx run`, Claude authentication flows, and every non-Claude provider keep their previous environment.
+
 ### Launch History
 
 Every interactive `cdx <name>` launch is recorded under `CDX_HOME`, including success/failure, duration, cwd, launch settings, and transcript path.
@@ -538,21 +538,22 @@ cdx history --summary --from 2026-05-01 --to 2026-05-28
 | `cdx runs [--limit N] [--since 7d\|today\|DATE] --json` | List recent runs; `--since` returns every run completed after the cursor and ignores `--limit` |
 | `cdx schema --json` | Publish the enums, mutually-exclusive argument groups, and error codes programmatic callers should validate against |
 | `cdx stats [name] [--since 7d\|today\|DATE] [--from DATE] [--to DATE] [--json]` | Aggregate launch counts, duration, and known headless token usage by session |
-| `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 [--json] [--refresh\|--cached] [--timeout SECONDS]` | Show token usage table for all sessions; empty credits, block, and reset columns are omitted; `--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] [--yes] [--autostart\|--no-autostart] [--alerts\|--no-alerts]` | Download the companion for this OS and architecture, verify its published checksum before unpacking, record what was written, and start it. Asks two separate questions: whether to launch it at login, and whether to notify you when an agent finishes a turn or waits for you. `--yes` answers both, each pair of flags answers one deterministically, and a non-interactive or `--json` run declines rather than acquiring a login item or writing provider hooks by accident. Accepting alerts turns them on for every supported session and for sessions created later. Refuses when no checksum is published for the asset |
+| `cdx tray install [--json] [--yes] [--autostart\|--no-autostart] [--alerts\|--no-alerts]` | Download the companion for this OS and architecture, verify its published checksum before unpacking, record what was written, and start it. It asks whether to launch at login; provider-hook consent is requested separately at the first eligible interactive session launch. Refuses when no checksum is published for the asset |
 | `cdx tray uninstall [--json]` | Remove exactly what `install` recorded, and nothing else |
 | — | `cdx update` also moves an installed companion to the new release, and says so. A companion already running keeps executing the build it started with, so it reports that too rather than leaving you to wonder why the menu looks unchanged |
 | `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 terminal [status\|set <app>\|clear] [--json]` | Choose which terminal a tray session row opens — `cdx tray terminal set iTerm`, `cdx tray terminal clear` to go back to the platform default. The value is an application name, never a command: anything that could be read as one is refused rather than sanitized. macOS opens it with `open -a`, Linux prefers it ahead of the emulators it already tries, and Windows honours `wt` because Windows Terminal is the one that documents how to be handed a command. A named terminal that is not installed falls back to the default rather than leaving the click doing nothing |
+| `cdx tray terminal [status\|list\|set <app>\|clear] [--json]` | Choose which terminal a tray session row opens; the tray exposes the same candidates plus **System default**. `cdx tray terminal list` reports candidates and the stored choice, and `clear` returns to the platform default. The value is an application name, never a command. A named terminal that disappears is reported unavailable and never silently replaced by another terminal. |
+| `cdx tray sort [status\|set <capacity\|reset\|recent>] [--json]` | Persist the tray session order: current capacity-first order, nearest reset first, or most recently launched first. This affects only the tray menu, never `cdx next` or automatic session selection. |
 | `cdx tray plugin [status\|enable <name>\|disable <name>\|run <action>] [--json]` | Turn a tray integration on or off, and list what is enabled. Opt-in in both directions and reversible; nothing enables one implicitly. `logics` is the only one that exists, and `status` says once when it is installed but not enabled. `run` is what the tray calls back with a card's action id and is not meant to be typed |
-| `cdx tray alerts [on\|off\|status] [--json]` | Silence agent alerts, or let them through again — the tray menu has the same switch. Muting stops the banner, not the record: events still reach a running companion, so the menu shows what you missed. It applies to the direct notification path too, so quitting the tray does not silently un-mute you. Distinct from the per-session `--notify` opt-in, which says which sessions may alert at all |
+| `cdx tray alerts [on\|off\|status] [--json]` | Silence agent alerts, or let them through again. These commands work with or without a running tray: with one, muted events remain in its menu; without one, delivery falls back directly to the desktop notification channel. In both cases `off` suppresses banners and `on` restores delivery for the next event, including hooks already running with an older launch environment. Distinct from provider-hook consent, which controls configuration writes |
 | `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 |
@@ -594,7 +595,9 @@ The companion is a native binary distributed as a release asset, not part of the
 
 - **Where the checksum comes from.** Releases older than the one you are running are vouched for by `checksums/release-archives.json`, committed to the repository before those assets existed. Your own release is a special case: its tray assets are built after the tag, so no package built at tag time can carry their checksums. For that one version CDX reads the ledger the release publishes beside the assets — the publisher's own assertion over the same channel, which catches a truncated download or a wrong-architecture asset but does not defend against someone who can rewrite the release itself.
 - **The checksum is the vouching, not Apple or Microsoft.** The macOS bundle is signed with a *self-signed* certificate. That signature exists because Apple Silicon refuses to execute unsigned arm64 code at all — it is not a claim that Apple reviewed anything. What actually vouches for the asset is the SHA-256 published in `checksums/release-archives.json`, verified before a single byte is unpacked. An asset with no published checksum is refused rather than installed hopefully.
-- **Tray integrations are cards, not plugins.** `cdx tray plugin enable logics` adds one section to the menu: a blocked/ready summary and at most two rows — the first blocked document, because it is what stops work, and the highest-priority task in progress, because it is what to do instead. Clicking a row opens the Logics viewer focused on it.
+- **Tray integrations are cards, not plugins.** `cdx tray plugin enable logics` adds one section to the menu: a blocked/ready summary and at most two rows — the first blocked document, because it is what stops work, and the highest-priority task in progress, because it is what to do instead. Clicking a row opens the Logics viewer focused on it. Tray openings ask Logics for a free local port, so an existing viewer is never displaced.
+
+- **Alert return path.** When an alert originated in iTerm2, the macOS tray row and native CDX notification focus that exact iTerm session. macOS may ask once for CDX to control iTerm; declining leaves the alert visible but does not focus a different window. Script Editor fallback banners and Windows/Linux notifications remain delivery-only.
 
   There is deliberately no marketplace, no discovery, no installation from a URL, and no plugin auto-update. An adapter is a function in this repository, named in a registry CDX owns, so nothing unknown can run. Adapters produce data and never behaviour: a card is a summary, rows, and action ids from a fixed vocabulary, and the tray hands an id back to CDX rather than running anything itself. Adding a capability is a change to CDX, reviewed like any other.
 
@@ -605,6 +608,7 @@ The companion is a native binary distributed as a release asset, not part of the
 - **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.
+- **About stays actionable.** The last tray action before Quit is `About (v<installed CDX version>)`; it opens the project’s GitHub page with the platform’s normal browser launcher.
 
 ## JSON Output
 
@@ -1047,6 +1051,10 @@ Without `--yes`, an interactive confirmation is required. `cdx` sends an idempot
 
 Contribution guidelines are available in [`CONTRIBUTING.md`](CONTRIBUTING.md).
 
+Working on the tray companion? [`docs/tray-local-testing.md`](docs/tray-local-testing.md)
+covers the local loops, from rendering the menu to stdout to running a real icon
+in the menu bar.
+
 ---
 
 ## License

package/VERSION

@@ -1 +1 @@
-0.18.6
+0.19.1

package/changelogs/CHANGELOGS_0_18_7.md

@@ -0,0 +1,5 @@
+# CDX Manager 0.18.7
+
+## Fixes
+
+- Interactive Claude sessions keep the cdx `session — folder` terminal title while Claude is running an action, instead of losing it to Claude's own animated title. Headless runs, Claude authentication flows, and other providers are unchanged.

package/changelogs/CHANGELOGS_0_19_0.md

@@ -0,0 +1,14 @@
+# CDX Manager 0.19.0
+
+## Features
+
+- Tray alerts can return to their originating iTerm session on macOS, including from a native notification banner.
+- The tray can group enabled Logics actions by repository and opens its viewer on a free local port.
+- The tray offers supported terminal choices and persists its session sort order.
+- Interactive launches ask for an optional agent-alert hook and support a validated manually entered launch directory.
+
+## Fixes
+
+- Tray session rows now show only meaningful quota reset columns and retain their selected terminal behavior across macOS, Windows, and WSL.
+- Existing provider hooks read the current alert mute setting, so `cdx tray alerts on|off` takes effect without a relaunch.
+- Local tray development helpers now use the checkout reliably on Windows and WSL.

package/changelogs/CHANGELOGS_0_19_1.md

@@ -0,0 +1,7 @@
+# CDX Manager 0.19.1
+
+## Fixes
+
+- Restored Linux tray companion builds and terminal fallback handling.
+- Removed the unused GTK dependency tree from the tray companion, resolving a Dependabot security alert.
+- Removed the outdated `cdx stats` image from the README.

package/checksums/release-archives.json

@@ -257,6 +257,32 @@
         "x86_64-pc-windows-msvc": "31a1743b0b6ec420a85c1679e93fcbd32c982a36e080a59d563276204682f152",
         "x86_64-unknown-linux-musl": "49fba26d3deeab1e46af542528a5c71262e6c4d82898fcf989d7222a09a11d59"
       }
+    },
+    "v0.18.6": {
+      "github_tarball_sha256": "31111eda2c31399b3fea14d80d10c0a2d10f15aab93a77a60939c86c564971ca",
+      "github_zip_sha256": "a3d78348416b3494645fa9f0467144c7e76b40d8862be959d125eb3d13805b15",
+      "tray_assets": {
+        "aarch64-apple-darwin": "aeb9267f72c3ee7426672d2e1fe98c0e39e0df795bbad6832299d4176c21022e",
+        "aarch64-unknown-linux-musl": "846969612d9a0e82f5f6cacc05aedc33153c1c325b8af95f63c8a2a5c2217261",
+        "x86_64-apple-darwin": "da5b4d3994fff9e616401e5a4cd01d68d216ddbeb6d41d96d67bbc789ef85118",
+        "x86_64-pc-windows-msvc": "296f760a7e10b7ef05936157b9de2b9d3b5e13f7ea2f57b7616705352ea97bd2",
+        "x86_64-unknown-linux-musl": "b360ea3ec14ab3aad0ccffcf477dee4bdadf6c1d4f150ef1cd13c7d293ae6829"
+      }
+    },
+    "v0.18.7": {
+      "github_tarball_sha256": "913d43fc57f29b5dae486d1be2e30a48aa9abdd37cce8bd7219e23b49c0b4045",
+      "github_zip_sha256": "f24a4cd9943372b7e7ee67fc112da7873fd832438b88236aa10428f029bb20e5",
+      "tray_assets": {
+        "aarch64-apple-darwin": "a8d5b8c6f474594a609f7172ef9a307698f588ca907a6649b1229e8a2e71d99f",
+        "aarch64-unknown-linux-musl": "1d26111f25cc19986fdc4641c6f27875f20f55c19c700e6dc8edfdb6aab78ccc",
+        "x86_64-apple-darwin": "1e79a847ba780e9818173a0ced2172c4e37a5fc2121003679603900662e41609",
+        "x86_64-pc-windows-msvc": "dc6b9b951526837a8adfe58cf56683fa6072a18488a47c093bc0ba492b588ba7",
+        "x86_64-unknown-linux-musl": "4affb9acf4b6ce1384af883fa9943cca7d76bb049d5562aa8d5498d51e7204a2"
+      }
+    },
+    "v0.19.0": {
+      "github_tarball_sha256": "d9816c0e4a2313bc10d8d9b527795b3027798607af49c5ef820f491d167176b4",
+      "github_zip_sha256": "656090f68694695fd947b0e73fc8c1ef66785054fd04054f8659b03997daedfb"
     }
   }
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "cdx-manager",
-  "version": "0.18.6",
+  "version": "0.19.1",
   "description": "Terminal session manager for Codex and Claude accounts.",
   "license": "MIT",
   "author": "Alexandre Agostini",

package/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "cdx-manager"
-version = "0.18.6"
+version = "0.19.1"
 description = "Terminal session manager for Codex and Claude accounts."
 readme = "README.md"
 requires-python = ">=3.9"

package/src/agent_notify.py

@@ -21,7 +21,6 @@ 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
@@ -55,6 +54,7 @@ _FAILURE_EVENTS = {"stopfailure"}
 _TRANSIENT_ERRORS = {"rate_limit", "overloaded", "server_error", "max_output_tokens"}
 _PREVIEW_LIMIT = 180
 _TOOL_NAME_LIMIT = 80
+_TERMINAL_ID_LIMIT = 128
 
 
 def supports_agent_alerts(provider):
@@ -127,10 +127,6 @@ def _is_reportable(payload, event):
 def compose_notification(payload, env=None, cwd=None):
     """Title and message for this event, or None if we should stay quiet."""
     env = os.environ if env is None else env
-    if env.get(ENABLED_ENV) == "0":
-        # Headless runs share the session's home, so they read the same hooks.
-        # Their caller already learns of completion from the return value.
-        return None
     session = env.get(SESSION_ENV)
     if not session:
         return None
@@ -201,6 +197,9 @@ def structured_details(payload, env=None, cwd=None):
         "project": os.path.basename(str(directory).rstrip("/\\")) or str(directory),
         "event": event,
     }
+    terminal_id = _notification_text(env.get("ITERM_SESSION_ID"), _TERMINAL_ID_LIMIT)
+    if terminal_id:
+        details["terminal"] = {"kind": "iterm2", "id": terminal_id}
     for key, source, limit in (
         ("tool", "tool_name", _TOOL_NAME_LIMIT),
         ("error_type", "error_type", _TOOL_NAME_LIMIT),
@@ -309,7 +308,7 @@ def handle_notify(rest, ctx):
 
 
 def launch_notify_env(session, enabled, env=None):
-    """Env the provider is launched with, carrying who we are and whether to notify.
+    """Env the provider is launched with, carrying who we are and privacy settings.
 
     `CDX_HOME` is pinned rather than inherited, and that is what makes tray
     routing work at all. It defaults to `~/.cdx`, resolved against `HOME` — and
@@ -321,9 +320,7 @@ def launch_notify_env(session, enabled, env=None):
     """
     env = os.environ if env is None else env
     values = {SESSION_ENV: session["name"], "CDX_HOME": get_cdx_home(env)}
-    if not enabled:
-        values[ENABLED_ENV] = "0"
-    elif (session.get("launch") or {}).get("notify_preview") is True:
+    if enabled and (session.get("launch") or {}).get("notify_preview") is True:
         values[PREVIEW_ENV] = "1"
     return values
 

package/src/cli.py

@@ -589,6 +589,7 @@ def main(argv, options=None):
         "signal_emitter": signal_emitter,
         "spawn": spawn,
         "spawn_detached": options.get("spawn_detached"),
+        "spawn_detached_runner": options.get("spawn_detached_runner"),
         "spawn_headless": options.get("spawn_headless"),
         # Stream `--prompt-file -` reads from. Distinct from "stdin", which is
         # the {"isTTY": ...} descriptor the interactive paths use.

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 [--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]"
+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|list|set <app>|clear] [--json] | cdx tray sort [status|set <capacity|reset|recent>] [--json]"
 
 RUN_TAIL_DEFAULT_LINES = 50
 RUN_TAIL_MAX_LINES = 2000

package/src/commands/launch.py

@@ -6,7 +6,7 @@ Split out of cli_commands.py. Moved verbatim; re-exported by cli_commands.
 import os
 import shlex
 
-from ..agent_notify import notifications_enabled, provision
+from ..agent_notify import notifications_enabled, provision, supports_agent_alerts
 from ..cli_args import CAN_RESUME_USAGE, HANDOFF_USAGE, RESUME_USAGE, _parse_json_flag
 from ..cli_helpers import (
     API_SCHEMA_VERSION,
@@ -66,14 +66,41 @@ def _launch_directory(session, ctx, explicit, json_flag):
     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
+    ask = ctx["options"].get("input") or input
+    other_index = len(choices) + 1
+    while True:
+        ctx["out"](
+            "Choose launch directory:\n"
+            + "".join(f"  {index + 1}. {path}\n" for index, path in enumerate(choices))
+            + f"  {other_index}. Other (enter a path)\n"
+        )
+        try:
+            answer = ask(f"Directory [1-{other_index}] (default {len(choices)}): ").strip()
+        except KeyboardInterrupt:
+            raise CdxError("Launch cancelled.", exit_code=130) from None
+        if not answer:
+            return cwd
+        try:
+            choice = int(answer)
+        except ValueError:
+            raise CdxError("Launch cancelled: choose a listed directory.") from None
+        if choice == other_index:
+            while True:
+                try:
+                    entered = ask("Directory path (blank to return): ").strip()
+                except KeyboardInterrupt:
+                    raise CdxError("Launch cancelled.", exit_code=130) from None
+                if not entered:
+                    break
+                directory = os.path.realpath(entered)
+                if os.path.isdir(directory):
+                    return directory
+                ctx["out"](f"Invalid directory: {entered}\n")
+            continue
+        try:
+            return choices[choice - 1]
+        except IndexError:
+            raise CdxError("Launch cancelled: choose a listed directory.") from None
 
 
 def _format_resume_capability(capability, use_color=False):
@@ -128,19 +155,51 @@ def handle_resume(rest, ctx):
         raise CdxError(RESUME_USAGE)
     return handle_launch(args[0], ctx, resume=True, force_json=json_flag, directory=directory)
 
+
+def _notification_provisioning_enabled(session, ctx, json_flag):
+    """Ask once before the first supported profile receives a hook."""
+    enabled = notifications_enabled(session)
+    if enabled or not supports_agent_alerts(session["provider"]):
+        return enabled
+    from ..tray_defaults import alerts_default, set_alerts_default
+
+    base_dir = ctx["service"]["base_dir"]
+    if alerts_default(base_dir):
+        return True
+    if not ctx["stdin_is_tty"] or json_flag:
+        return False
+    ask = ctx.get("options", {}).get("input") or input
+    try:
+        answer = ask("Allow CDX to install this provider's agent-alert hook? [y/N] ").strip().lower()
+    except EOFError:
+        return False
+    if answer not in ("y", "yes"):
+        return False
+    set_alerts_default(base_dir, True)
+    from ..tray_alerts import set_alerts
+    set_alerts(base_dir, False)
+    return True
+
+
 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
     warnings = _update_notice_warnings(ctx)
     _warn_if_session_already_running(command, ctx)
-    session = ctx["service"]["launch_session"](command)
+    session = ctx["service"]["get_session"](command)
+    if not session:
+        raise CdxError(f"Unknown session: {command}")
+    if session.get("enabled", True) is False:
+        raise CdxError(f"Session is disabled: {command}")
     capability = _resume_capability_for_session(session, ctx) if resume else None
     if capability and not capability["resumable"]:
         raise CdxError(
             f"Provider {session['provider']} does not support native resume through cdx."
         )
     cwd = _launch_directory(session, ctx, directory, json_flag)
+    session = ctx["service"]["launch_session"](command)
+    capability = _resume_capability_for_session(session, ctx) if resume else None
     if not json_flag and not ctx["stdin_is_tty"]:
         ctx["out"](f"Using directory: {cwd}\n")
     _ensure_session_authentication(
@@ -162,10 +221,11 @@ def handle_launch(command, ctx, initial_prompt=None, resume=False, force_json=No
     if not json_flag:
         ctx["out"](f"{_info(message, ctx['use_color'])}\n")
         _write_update_notice(ctx)
+    alerts_allowed = _notification_provisioning_enabled(session, ctx, json_flag)
     installed = provision(
         _get_auth_home(session),
         session["provider"],
-        notifications_enabled(session),
+        alerts_allowed,
         ctx.get("env"),
         spawn_sync=ctx.get("spawn_sync"),
         base_dir=ctx["service"]["base_dir"],

package/src/commands/settings.py

@@ -58,6 +58,7 @@ def _notification_setting_notice(settings, sessions, action):
             notices.append(f"Agent alerts updated for {names} — this provider does not support notification hooks.")
         return "\n".join(notices)
     if "notify_preview" in settings:
+        names = _format_bulk_launch_summary(sessions)
         if action == "set" and settings["notify_preview"]:
             return f"Response previews enabled for {names} — completion text may be visible on the lock screen."
         return f"Response previews disabled for {names}."

package/src/commands/tray.py

@@ -46,11 +46,11 @@ from ..tray_install import (
 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
+from ..tray_terminal import clear_terminal, set_sort, set_terminal, sort_preference, terminal_candidates, terminal_preference
 
 TRAY_ACTIONS = (
     "status", "install", "launch", "uninstall", "autostart", "doctor",
-    "events", "ack", "heartbeat", "alerts", "plugin", "terminal",
+    "events", "ack", "heartbeat", "alerts", "plugin", "terminal", "sort",
 )
 
 # Codes rather than prose, so a caller can branch on them.
@@ -95,6 +95,8 @@ def handle_tray(rest, ctx):
         return _tray_plugin(args, ctx)
     if action == "terminal":
         return _tray_terminal(args, ctx)
+    if action == "sort":
+        return _tray_sort(args, ctx)
     return _tray_install(args, ctx)
 
 
@@ -138,6 +140,8 @@ def _tray_status(args, ctx):
         refreshable=not any(row.get("active") for row in rows),
         plugins=cards,
         terminal=terminal_preference(ctx["service"]["base_dir"]),
+        terminal_candidates=terminal_candidates(),
+        sort=sort_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
@@ -423,6 +427,14 @@ def _tray_terminal(args, ctx):
             set_terminal(base_dir, positional[1])
         except ValueError:
             return _refuse(ctx, parsed["json"], "tray.terminal", TERMINAL_INVALID, TERMINAL_REFUSAL)
+    elif mode == "list":
+        chosen = terminal_preference(base_dir)
+        candidates = terminal_candidates()
+        if parsed["json"]:
+            _write_json(ctx, _json_success("tray.terminal", "Listed launchable terminals", terminal=chosen, candidates=candidates, applied=False))
+            return 0
+        ctx["out"]("Launchable terminals: " + (", ".join(candidates) or "none") + "\n")
+        return 0
     elif mode != "status":
         raise CdxError(TRAY_USAGE)
 
@@ -445,6 +457,28 @@ def _tray_terminal(args, ctx):
     return 0
 
 
+def _tray_sort(args, ctx):
+    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 == "set" and len(positional) == 2:
+        try:
+            sort = set_sort(base_dir, positional[1])
+        except ValueError as error:
+            raise CdxError(str(error)) from None
+    elif mode == "status":
+        sort = sort_preference(base_dir)
+    else:
+        raise CdxError(TRAY_USAGE)
+    message = f"Tray sessions sort by {sort}."
+    if parsed["json"]:
+        _write_json(ctx, _json_success("tray.sort", message, sort=sort, applied=mode == "set"))
+    else:
+        ctx["out"](f"{message}\n")
+    return 0
+
+
 def _tray_plugin(args, ctx):
     """Turn an integration on or off, and say what is on.
 
@@ -454,6 +488,7 @@ def _tray_plugin(args, ctx):
     """
     parsed = _parse_flag_args(args, {
         "--json": {"key": "json", "type": "bool", "default": False},
+        "--root": {"key": "root", "type": "str", "default": None},
     }, TRAY_USAGE, positionals_key="args", max_positionals=2)
     positional = parsed["args"] or ["status"]
     mode = positional[0]
@@ -515,7 +550,7 @@ def _tray_plugin_run(rest, parsed, ctx):
 
     if not rest:
         raise CdxError(TRAY_USAGE)
-    result = perform_action(rest[0], ctx)
+    result = perform_action(rest[0], ctx, root=parsed["root"])
     if not result["ok"]:
         return _refuse(ctx, parsed["json"], "tray.plugin.run", result["code"], result["message"])
     if parsed["json"]:

package/src/logics_view.py

@@ -36,3 +36,13 @@ def run_logics_viewer(executable, cwd, env=None, extra_args=None, runner=None):
     if runner is subprocess.run:
         return subprocess.run(argv, cwd=cwd, env=merged_env)
     return runner(argv, cwd=cwd, env=merged_env)
+
+
+def spawn_logics_viewer(executable, cwd, env=None, extra_args=None, runner=None):
+    """Start the long-running viewer without making a tray click wait for it."""
+    argv = [executable, "view"] + (extra_args or [])
+    merged_env = {**os.environ, **(env or {})}
+    return (runner or subprocess.Popen)(
+        argv, cwd=cwd, env=merged_env, stdin=subprocess.DEVNULL,
+        stdout=subprocess.DEVNULL, stderr=subprocess.DEVNULL, start_new_session=True,
+    )

package/src/provider_runtime.py

@@ -108,6 +108,9 @@ def headless_permission_disables_network(provider, permission):
 
 
 REDACTED_PROMPT_ARG = "[prompt redacted]"
+# Documented Claude Code switch that stops it from setting and clearing the
+# terminal title, leaving cdx's shared title keeper as the only writer.
+CLAUDE_DISABLE_TERMINAL_TITLE_ENV = "CLAUDE_CODE_DISABLE_TERMINAL_TITLE"
 CLAUDE_CLI_MODEL_ALIASES = {
     "claude-sonnet": "sonnet",
     "claude-opus": "opus",
@@ -148,11 +151,23 @@ def _anthropic_credentials_path(auth_home):
     return os.path.join(auth_home, "credentials", f"{_anthropic_profile_name()}.json")
 
 
-def _claude_env(base_env, auth_home):
+def _claude_env(base_env, auth_home, own_terminal_title=False):
+    """Build the Claude provider environment for one cdx spawn.
+
+    `own_terminal_title` is set by the interactive launch/resume paths, where
+    cdx's title keeper owns the `session — folder` title. Claude Code redraws an
+    animated busy title far more often than the keeper re-emits, so we tell it
+    to leave the title alone; its in-TUI activity indicator is unaffected. The
+    value is forced rather than defaulted so an ambient `0` in the operator's
+    shell cannot hand the title back to Claude. Headless and auth spawns do not
+    own a title and keep their previous environment.
+    """
     env = {**base_env, **_home_env_overrides(auth_home)}
     env.pop("CLAUDE_CONFIG_DIR", None)
     env.pop("CODEX_HOME", None)
     env.setdefault("ANTHROPIC_PROFILE", _anthropic_profile_name())
+    if own_terminal_title:
+        env[CLAUDE_DISABLE_TERMINAL_TITLE_ENV] = "1"
     return env
 
 
@@ -547,7 +562,7 @@ def _build_launch_spec(session, cwd=None, env_override=None, initial_prompt=None
         if initial_prompt:
             args.append(initial_prompt)
         auth_home = _get_auth_home(session)
-        claude_env = _claude_env(env, auth_home)
+        claude_env = _claude_env(env, auth_home, own_terminal_title=True)
         oauth_token = _read_claude_launch_oauth_token(auth_home)
         if oauth_token:
             claude_env["CLAUDE_CODE_OAUTH_TOKEN"] = oauth_token
@@ -693,7 +708,7 @@ def _build_resume_spec(session, cwd=None, env_override=None, capture_transcript=
         if resume_prompt:
             args.append(resume_prompt)
         auth_home = _get_auth_home(session)
-        claude_env = _claude_env(env, auth_home)
+        claude_env = _claude_env(env, auth_home, own_terminal_title=True)
         oauth_token = _read_claude_launch_oauth_token(auth_home)
         if oauth_token:
             claude_env["CLAUDE_CODE_OAUTH_TOKEN"] = oauth_token

package/src/status_view.py

@@ -75,26 +75,38 @@ def _format_credits(value, empty="n/a"):
 
 
 def _format_status_rows(rows, use_color=False, small=False):
+    active_rows = [r for r in rows if r.get("enabled", True) is not False]
+    def positive(value):
+        try:
+            return float(value) > 0
+        except (TypeError, ValueError):
+            return False
+    reset_visible = [
+        any(positive(r.get("reset_credits_available")) for r in active_rows),
+        any(r.get("reset_5h_at") for r in active_rows),
+        any(r.get("reset_week_at") for r in active_rows),
+    ]
+    block_visible = any(_format_blocking_quota(r) not in ("-", "?") for r in active_rows)
+    credits_visible = any(r.get("credits") is not None for r in active_rows)
     has_provider = len({r["provider"] for r in rows}) > 1 and not small
     has_label = any(r.get("label") for r in rows) and not small
     if small:
-        headers = ["SESSION", "STATUS", "OK", "5H", "WEEK", "RESETS", "RESET 5H", "RESET WEEK"]
+        headers = ["SESSION", "STATUS", "OK", "5H", "WEEK"] + [name for name, visible in zip(["RESETS", "RESET 5H", "RESET WEEK"], reset_visible) if visible]
     elif has_provider:
         headers = ["SESSION", "PROV."]
         if has_label:
             headers.append("LABEL")
-        headers += ["STATUS", "AUTH", "OK", "5H", "WEEK", "BLOCK", "CR", "RESETS", "RESET 5H", "RESET WEEK", "UPDATED"]
+        headers += ["STATUS", "AUTH", "OK", "5H", "WEEK"] + (["BLOCK"] if block_visible else []) + (["CR"] if credits_visible else []) + [name for name, visible in zip(["RESETS", "RESET 5H", "RESET WEEK"], reset_visible) if visible] + ["UPDATED"]
     else:
         headers = ["SESSION"]
         if has_label:
             headers.append("LABEL")
-        headers += ["STATUS", "AUTH", "OK", "5H", "WEEK", "BLOCK", "CR", "RESETS", "RESET 5H", "RESET WEEK", "UPDATED"]
+        headers += ["STATUS", "AUTH", "OK", "5H", "WEEK"] + (["BLOCK"] if block_visible else []) + (["CR"] if credits_visible else []) + [name for name, visible in zip(["RESETS", "RESET 5H", "RESET WEEK"], reset_visible) if visible] + ["UPDATED"]
     if not rows:
         if small:
             return "SESSION  STATUS  OK  5H  WEEK  RESETS  RESET 5H  RESET WEEK\nNo saved sessions yet."
         return "SESSION  STATUS  OK  5H  WEEK  BLOCK  CR  RESETS  RESET 5H  RESET WEEK  UPDATED\nNo saved sessions yet."
     headers = [_style(header, "1", use_color) for header in headers]
-    active_rows = [r for r in rows if r.get("enabled", True) is not False]
     priority = recommend_priority_rows(rows)
     disabled_rows = sorted(
         [r for r in rows if r.get("enabled", True) is False],
@@ -130,16 +142,16 @@ def _format_status_rows(rows, use_color=False, small=False):
                 _style_reset_time(r.get("reset_week_at"), use_color),
             ]
         if small:
-            base += usage_columns
+            base += usage_columns[:3] + [value for value, visible in zip(usage_columns[3:], reset_visible) if visible]
         else:
             block = "-" if r.get("enabled", True) is False else _format_blocking_quota(r)
             credits = _format_credits(r.get("credits"), empty="-")
-            base += usage_columns[:3] + [
-                _style(block, "33" if block not in ("?", "-") else "2", use_color),
-                _style(credits, "33" if r.get("credits") is not None else "2", use_color),
-                *usage_columns[3:],
-                _style(_format_relative_age(r.get("updated_at")), "2", use_color),
-            ]
+            base += usage_columns[:3]
+            if block_visible:
+                base.append(_style(block, "33" if block not in ("?", "-") else "2", use_color))
+            if credits_visible:
+                base.append(_style(credits, "33" if r.get("credits") is not None else "2", use_color))
+            base += [*[value for value, visible in zip(usage_columns[3:], reset_visible) if visible], _style(_format_relative_age(r.get("updated_at")), "2", use_color)]
         table_rows.append(base)
     # "Recommended", not "Priority": the `--priority` setting is one input to
     # this ranking among several, and labelling the whole recommendation with

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 = 2
+SCHEMA_MINOR = 3
 
 # 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
@@ -139,6 +139,7 @@ def menu_session(row, now):
         "freshness": freshness,
         "age_seconds": None if age is None else int(age),
         "updated_at": row.get("updated_at"),
+        "last_launched_at": row.get("last_launched_at"),
     }
 
 
@@ -223,13 +224,17 @@ def tooltip_for(worst):
     return "CDX · " + " · ".join(parts)
 
 
-def build_snapshot(rows, now, cdx_version, refreshable=True, plugins=None, terminal=None):
+def build_snapshot(rows, now, cdx_version, refreshable=True, plugins=None, terminal=None, terminal_candidates=None, sort="capacity"):
     """The whole contract, from the rows `cdx status` already returns.
 
     `icon` carries no session name, account, or figure: it is what shows while
     the menu is closed, and `req_035` AC3 forbids leaking anything there.
     """
     sessions = _by_urgency([menu_session(row, now) for row in rows if _eligible(row)])
+    if sort == "reset":
+        sessions.sort(key=lambda row: (_reset_sort_key(row), row["name"]))
+    elif sort == "recent":
+        sessions.sort(key=lambda row: (_recent_sort_key(row), row["name"]))
     if not sessions:
         icon = {
             "state": ICON_UNKNOWN,
@@ -263,9 +268,23 @@ def build_snapshot(rows, now, cdx_version, refreshable=True, plugins=None, termi
         # other durable tray preference already lives in CDX and a second store
         # is a second thing to keep in step.
         "terminal": terminal,
+        "terminal_candidates": list(terminal_candidates or []),
+        "sort": sort if sort in ("capacity", "reset", "recent") else "capacity",
     }
 
 
+def _reset_sort_key(row):
+    from .status_view import _parse_reset_timestamp
+    value = _parse_reset_timestamp(row.get("reset_at"))
+    return value if value is not None else float("inf")
+
+
+def _recent_sort_key(row):
+    from .status_view import _parse_reset_timestamp
+    value = _parse_reset_timestamp(row.get("last_launched_at"))
+    return -value if value is not None else float("inf")
+
+
 def read_snapshot(payload):
     """Read a snapshot that may be newer than this reader.
 

package/src/tray_logics.py

@@ -20,6 +20,8 @@ from .logics_view import resolve_logics_manager
 from .tray_plugins import ADAPTER_TIMEOUT_SECONDS, CARD_TTL_SECONDS
 
 _PRIORITY_ORDER = {"high": 0, "medium": 1, "low": 2}
+_MAX_GROUPS = 5
+_MAX_ROWS_PER_GROUP = 2
 
 
 def logics_card(env=None, now=None, cache=None, runner=None, executable=None, directories=None):
@@ -96,20 +98,18 @@ def _status(env=None, runner=None, executable=None, directories=None):
     return payloads if roots else (payloads[0][1] if payloads else None)
 
 
-def _card_from_status(status):
+def _card_from_status(status, root=None):
     if isinstance(status, list):
-        cards = [(root, _card_from_status(payload), len(payload.get("blocked_docs") or [])) for root, payload in status]
-        cards = [(root, card, blocked) for root, card, blocked in cards if card]
-        if not cards:
+        groups = []
+        for root, payload in status:
+            card = _card_from_status(payload, root)
+            if card:
+                groups.append({"root": root, "label": _repository_label(root, [item[0] for item in status]), "rows": card["rows"][:_MAX_ROWS_PER_GROUP]})
+        groups = [group for group in groups if group["rows"]][:_MAX_GROUPS]
+        if not groups:
             return None
-        root, card, _ = sorted(cards, key=lambda item: (-item[2], -len(item[1]["rows"]), item[0] or ""))[0]
-        repository_count = len(cards)
-        blocked_count = sum(item[2] for item in cards)
-        card["summary"] = f"{repository_count} repositories · {blocked_count} blocked"
-        prefix = os.path.basename(root or "")
-        for row in card["rows"]:
-            row["label"] = f"{prefix}: {row['label']}"
-        return card
+        blocked_count = sum(len(payload.get("blocked_docs") or []) for _, payload in status if isinstance(payload, dict))
+        return {"title": "Logics", "summary": f"{len(groups)} repositories · {blocked_count} blocked", "rows": [], "groups": groups, "actions": ["logics.open", "logics.refresh"]}
     if not isinstance(status, dict):
         return None
     blocked = [doc for doc in (status.get("blocked_docs") or []) if isinstance(doc, dict)]
@@ -126,9 +126,9 @@ def _card_from_status(status):
         }
     rows = []
     if blocked:
-        rows.append(_row(blocked[0], "blocked"))
+        rows.append(_row(blocked[0], "blocked", root))
     if active:
-        rows.append(_row(_most_urgent(active), "next"))
+        rows.append(_row(_most_urgent(active), "next", root))
     return {
         "title": "Logics",
         "summary": f"{len(blocked)} blocked · {len(active)} in progress",
@@ -155,9 +155,22 @@ def _progress(task):
     return value if isinstance(value, (int, float)) else 0
 
 
-def _row(doc, kind):
+def _row(doc, kind, root=None):
     ref = doc.get("ref")
     title = doc.get("title") or ref
     if not isinstance(ref, str) or not ref or not isinstance(title, str):
         return None
-    return {"label": f"{kind}: {title}", "action": f"logics.focus:{ref}"}
+    row = {"label": f"{kind}: {title}", "action": f"logics.focus:{ref}"}
+    if root:
+        row["root"] = root
+    return row
+
+
+def _repository_label(root, roots):
+    """A distinct local label without leaking the full local path."""
+    name = os.path.basename(root or "") or "repository"
+    collisions = [item for item in roots if os.path.basename(item or "") == name]
+    if len(collisions) < 2:
+        return name
+    parent = os.path.basename(os.path.dirname(root or ""))
+    return f"{parent}/{name}" if parent else name

package/src/tray_plugin_actions.py

@@ -10,12 +10,14 @@ different id. An id CDX does not recognise is refused, and refusal is the
 default branch rather than the exception — so an integration gaining a new
 capability is a change to this file, reviewed like any other.
 """
+import os
+
 from .errors import CdxError
 
 ACTION_UNKNOWN = "tray_plugin_action_unknown"
 
 
-def perform_action(action, ctx):
+def perform_action(action, ctx, root=None):
     """Run one action id. Never raises for a bad id: it reports."""
     if not isinstance(action, str) or "." not in action:
         return _unknown(action)
@@ -31,21 +33,25 @@ def perform_action(action, ctx):
     if verb == "open":
         return _open_viewer(ctx, None)
     if verb == "focus" and reference:
-        return _open_viewer(ctx, reference)
+        return _open_viewer(ctx, reference, root)
     return _unknown(action)
 
 
-def _open_viewer(ctx, reference):
-    from .logics_view import missing_logics_manager_failure, resolve_logics_manager, run_logics_viewer
+def _open_viewer(ctx, reference, root=None):
+    from .logics_view import missing_logics_manager_failure, resolve_logics_manager, spawn_logics_viewer
 
     executable = resolve_logics_manager(ctx.get("env") or {})
     if not executable:
         failure = missing_logics_manager_failure()
         return {"ok": False, "code": failure["code"], "message": failure["message"]}
-    extra = ["--focus", reference] if reference else []
+    if reference and not _valid_root(root):
+        return {"ok": False, "code": "logics_viewer_root_invalid", "message": "The focused Logics action has no valid repository context."}
+    # A tray click must coexist with any viewer already serving another repo.
+    # Port 0 is Logics' documented request for a free local port.
+    extra = ["--focus", reference, "--open", "--port", "0"] if reference else ["--fleet", "--open", "--port", "0"]
     try:
-        run_logics_viewer(
-            executable, ctx.get("cwd"), env=ctx.get("env"),
+        spawn_logics_viewer(
+            executable, root if reference else ctx.get("cwd"), env=ctx.get("env"),
             extra_args=extra, runner=ctx.get("spawn_detached_runner"),
         )
     except (OSError, CdxError) as error:
@@ -54,6 +60,15 @@ def _open_viewer(ctx, reference):
     return {"ok": True, "code": None, "message": f"Opened the Logics viewer{where}."}
 
 
+def _valid_root(root):
+    return (
+        isinstance(root, str)
+        and os.path.isabs(root)
+        and "\x00" not in root
+        and os.path.exists(os.path.join(root, ".git"))
+    )
+
+
 def _unknown(action):
     return {
         "ok": False,

package/src/tray_plugins.py

@@ -108,7 +108,11 @@ def bounded_card(raw, plugin):
         action = row.get("action")
         if not label or not _valid_action(action, plugin):
             continue
-        rows.append({"label": label, "action": action})
+        root = row.get("root")
+        if root is not None:
+            if plugin != "logics" or not action.startswith("logics.focus:") or not _valid_root(root):
+                continue
+        rows.append({"label": label, "action": action, **({"root": root} if root else {})})
     actions = [a for a in (raw.get("actions") or []) if _valid_action(a, plugin)]
     return {
         "plugin": plugin,
@@ -128,6 +132,10 @@ def _valid_action(action, plugin):
     )
 
 
+def _valid_root(root):
+    return isinstance(root, str) and os.path.isabs(root) and "\x00" not in root and len(root) <= 4096
+
+
 def collect_cards(base_dir, env=None, now=None, adapters=None, cache=None, directories=None):
     """Every enabled plugin's card, bounded, with failures dropped.
 

package/src/tray_terminal.py

@@ -16,8 +16,12 @@ platform's own launcher resolves it.
 import json
 import os
 import re
+import shutil
+import subprocess
+import sys
 
 STATE_VERSION = 1
+SORT_VALUES = ("capacity", "reset", "recent")
 # An application name or a bundle identifier, and nothing that could be read as
 # a command. No slashes, so it cannot name a path; no quotes, semicolons,
 # ampersands, pipes, backticks or dollars, so it cannot carry a shell fragment;
@@ -42,35 +46,70 @@ def terminal_preference(base_dir):
     preference. A value that fails validation today must not be honoured just
     because it was written before the rule existed.
     """
-    try:
-        with open(state_path(base_dir), encoding="utf-8") as handle:
-            state = json.load(handle)
-    except (OSError, ValueError):
-        return None
+    state = _state(base_dir)
     if not isinstance(state, dict) or state.get("version") != STATE_VERSION:
         return None
     name = state.get("terminal")
     return name if isinstance(name, str) and _NAME.match(name) else None
 
 
+def sort_preference(base_dir):
+    state = _state(base_dir)
+    value = state.get("sort")
+    return value if value in SORT_VALUES else "capacity"
+
+
 def valid_terminal(name):
     return isinstance(name, str) and bool(_NAME.match(name))
 
 
+def terminal_candidates(platform=None, which=None, available=None):
+    """Known launchable applications on this host; no guessed executables."""
+    platform = platform or sys.platform
+    which = which or shutil.which
+    names = ["Terminal", "iTerm", "Ghostty", "WezTerm"] if platform == "darwin" else (["wt", "powershell", "pwsh", "cmd"] if platform.startswith("win") else ["x-terminal-emulator", "gnome-terminal", "konsole", "xterm"])
+    if platform == "darwin":
+        available = available or (lambda name: subprocess.run(["open", "-Ra", name], stdout=subprocess.DEVNULL, stderr=subprocess.DEVNULL).returncode == 0)
+        return [name for name in names if available(name)]
+    return [name for name in names if which(name)]
+
+
 def set_terminal(base_dir, name):
     """Record a preferred terminal. Raises ValueError on anything else."""
     if not valid_terminal(name):
         raise ValueError(REFUSAL)
-    _write(base_dir, {"version": STATE_VERSION, "terminal": name})
+    state = _state(base_dir)
+    state["terminal"] = name
+    _write(base_dir, state)
     return name
 
 
 def clear_terminal(base_dir):
     """Return to the platform's default."""
-    _write(base_dir, {"version": STATE_VERSION, "terminal": None})
+    state = _state(base_dir)
+    state["terminal"] = None
+    _write(base_dir, state)
     return None
 
 
+def set_sort(base_dir, value):
+    if value not in SORT_VALUES:
+        raise ValueError("Tray sort must be capacity, reset, or recent.")
+    state = _state(base_dir)
+    state["sort"] = value
+    _write(base_dir, state)
+    return value
+
+
+def _state(base_dir):
+    try:
+        with open(state_path(base_dir), encoding="utf-8") as handle:
+            state = json.load(handle)
+    except (OSError, ValueError):
+        state = {}
+    return state if isinstance(state, dict) and state.get("version") == STATE_VERSION else {"version": STATE_VERSION}
+
+
 def _write(base_dir, state):
     path = state_path(base_dir)
     os.makedirs(os.path.dirname(path), exist_ok=True)