cdx-manager 0.23.0 → 0.24.0

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.23.0-4C8BF5) ![Python](https://img.shields.io/badge/python-3.9%2B-3776AB?logo=python&logoColor=white)
+[![License](https://img.shields.io/badge/license-MIT-4C8BF5)](LICENSE) ![Version](https://img.shields.io/badge/version-v0.24.0-4C8BF5) ![Python](https://img.shields.io/badge/python-3.9%2B-3776AB?logo=python&logoColor=white)
 
 **The right AI coding account, when you need it.** CDX Manager keeps your Codex and Claude accounts in separate profiles, shows which ones have quota, and helps you pick the next usable session from your terminal.
 
@@ -38,6 +38,7 @@ cdx work
 | Continue work in another session | `cdx handoff source target` | [Context handoff](docs/features.md#context-handoff) |
 | Run a prompt from a script | `cdx run --prompt "..." --json` | [Headless automation](docs/features.md#headless-automation) |
 | Inspect usage or get an alert | `cdx stats`, `cdx ready` | [Maintenance and notifications](docs/sessions-and-notifications.md) |
+| See which agents wait for you | `cdx agents --json` | [Agent state](docs/sessions-and-notifications.md#agent-state) |
 
 CDX checks authentication before interactive launches. Handoff keeps the source transcript in place and asks the receiving agent to verify the conversation and workspace before acting. No account switch or prompt submission happens just because you run `cdx next`.
 

package/VERSION

@@ -1 +1 @@
-0.23.0
+0.24.0

package/changelogs/CHANGELOGS_0_24_0.md

@@ -0,0 +1,16 @@
+# CDX Manager 0.24.0
+
+This release lets a dashboard, a terminal board or a chat agent ask cdx which sessions are working, waiting for their user, done or stopped by a usage limit, and lets detached background runs fail over to another account.
+
+## Agent state
+
+- `cdx set <name> --agent-state on` installs the provider hooks that record each session's state, without desktop alerts; sessions with `--notify on` record it too.
+- Every hook event updates one small record per session under `$CDX_HOME/state/agents/`, written atomically, even when alerts are muted.
+- `cdx agents [--max-age-hours N] [--json]` lists them, waiting first: `working`, `waiting`, `done`, `failed`, `limit` (with `reset_at` when known) or `ended` when the launching process is gone. Records older than N hours (24 by default) are dropped.
+- A `limit` state needs the same two signals as run failover: the provider's own exhaustion error and a refreshed account status that confirms it.
+- The prompt head (120 characters) is kept only with `--notify-preview on`.
+- Codex has no failure hook, so a Codex session never reaches `failed` or `limit`. Codex plugins installed before this release keep their old hooks until reinstalled (`--notify off`, one launch, `--notify on`).
+
+## Runs
+
+- `cdx run --detach --failover` is now accepted: the detached child watches the run and applies the failover rule, and the run registry records each move under the same `run_id`.

package/checksums/release-archives.json

@@ -562,6 +562,17 @@
         "x86_64-pc-windows-msvc": "37ddbc3464014a04a4fefee4cebeb24f16b3d06995844369bee8360526538d43",
         "x86_64-unknown-linux-musl": "6602e175632b7a191434b627bfef1e430d32da90ce0e23379bdf38700ea9ba7c"
       }
+    },
+    "v0.23.0": {
+      "github_tarball_sha256": "45daac760229b4bc5355628f1f9e5f46c6e61eecc5a320a2ecc31fec2f261f85",
+      "github_zip_sha256": "d5f1750548fe8445066fd0328f8c76a8035278537c29d1b39756fbdef8212915",
+      "tray_assets": {
+        "aarch64-apple-darwin": "98a68a5e98a1708475164fd252eb4e3fdf185cf2c62486f92a625d42c18c69ee",
+        "aarch64-unknown-linux-musl": "3dfa8764947edcb7da33e72af70cfc0ce3d4007c9ce0a1fcd4884848af0f5dd7",
+        "x86_64-apple-darwin": "00444fd894998db84ad6ab608f528061f6a9f0b50648ecfe61a91c6efdc4e969",
+        "x86_64-pc-windows-msvc": "bf35f8d25bbc34730533807df0d9c0e3f7ea2a271f268856759ae87bc9e116fe",
+        "x86_64-unknown-linux-musl": "60400fd7d10b0563503afc5bd741f7fefff4276d077fc6e4927f087390d46ccd"
+      }
     }
   }
 }

package/docs/cli.md

@@ -24,8 +24,8 @@
 | `cdx config <name> [--json]` | Show persistent launch settings for a session |
 | `cdx configs [--json]` | Show persistent launch settings for all sessions in one table |
 | `cdx power\|perm\|fast\|model <name\|all\|provider:PROVIDER\|a,b> <value\|default> [--json]` | Shortcut commands for setting or clearing one launch setting |
-| `cdx set <name>\|--sessions all\|a,b\|--provider PROVIDER [--power minimal\|low\|medium\|high\|xhigh] [--permission review\|default\|auto\|full] [--fast on\|off] [--rtk on\|off] [--logics on\|off] [--notify on\|off] [--notify-preview on\|off] [--scrub-env on\|off] [--shared-memory on\|off] [--retro on\|off] [--policy use\|ask-first\|never] [--model MODEL] [--fallback-model MODEL[,MODEL...]] [--budget USD] [--extra-args 'ARGS'] [--priority 0..100] [--json]` | Persist launch settings for one or more sessions |
-| `cdx unset <name>\|--sessions all\|a,b\|--provider PROVIDER (--power\|--reasoning-effort\|--permission\|--fast\|--rtk\|--logics\|--notify\|--notify-preview\|--scrub-env\|--shared-memory\|--retro\|--policy\|--model\|--fallback-model\|--budget\|--extra-args\|--priority\|--all) [--json]` | Remove persisted launch settings and fall back to provider defaults |
+| `cdx set <name>\|--sessions all\|a,b\|--provider PROVIDER [--power minimal\|low\|medium\|high\|xhigh] [--permission review\|default\|auto\|full] [--fast on\|off] [--rtk on\|off] [--logics on\|off] [--notify on\|off] [--agent-state on\|off] [--notify-preview on\|off] [--scrub-env on\|off] [--shared-memory on\|off] [--retro on\|off] [--policy use\|ask-first\|never] [--model MODEL] [--fallback-model MODEL[,MODEL...]] [--budget USD] [--extra-args 'ARGS'] [--priority 0..100] [--json]` | Persist launch settings for one or more sessions |
+| `cdx unset <name>\|--sessions all\|a,b\|--provider PROVIDER (--power\|--reasoning-effort\|--permission\|--fast\|--rtk\|--logics\|--notify\|--agent-state\|--notify-preview\|--scrub-env\|--shared-memory\|--retro\|--policy\|--model\|--fallback-model\|--budget\|--extra-args\|--priority\|--all) [--json]` | Remove persisted launch settings and fall back to provider defaults |
 | `cdx history [name] [--limit N] [--summary] [--since 7d\|today\|DATE] [--from DATE] [--to DATE] [--json]` | Show recent launch history or aggregate total launch time per assistant, optionally filtered by period |
 | `cdx last [--json]` | Launch the most recent existing session from launch history |
 | `cdx resume <name> [--conversation <id>] [--json]` | Resume the provider-native conversation for a session using the named command form; `--conversation` reopens that exact conversation and refuses with `conversation_not_found` if the profile has no such transcript |
@@ -50,10 +50,11 @@
 | `cdx update [--check] [--yes] [--json] [--version TAG]` | Update cdx-manager using the installer that matches how it was installed |
 | `cdx update all [--yes] [--json]` | Check installed providers, RTK, and Ponytail across Codex profiles; show the plan and ask once before applying safe native/Homebrew updates and missing RTK/Ponytail setup |
 | `cdx ready [--refresh] [--json]` | Schedule an OS notification for the next cooling-down assistant that becomes ready, then return immediately |
-| `cdx notify` | Internal provider hook target for agent alerts; use `cdx set <name> --notify on` to enable it |
+| `cdx notify` | Internal provider hook target for agent alerts and agent state; use `cdx set <name> --notify on` or `--agent-state on` to enable it |
+| `cdx agents [--max-age-hours N] [--json]` | Each session's last known agent state (working, waiting, done, failed, limit, ended), waiting first; records older than N hours (default 24) are dropped. See [Agent state](sessions-and-notifications.md#agent-state) |
 | `cdx next [--json] [--refresh]` | Select the best next assistant using the same priority logic as `cdx status` |
 | `cdx select --provider PROVIDER [--min-reasoning-effort minimal\|low\|medium\|high\|xhigh] [--min-power minimal\|low\|medium\|high\|xhigh] [--require-ready] [--refresh] --json` | Select a suitable session for headless automation |
-| `cdx run [session] --cwd PATH (--prompt-file PATH\|--prompt TEXT\|--prompt-file -) [--provider PROVIDER] [--model MODEL] [--kind assistant\|code-review\|retro] [--reasoning-effort minimal\|low\|medium\|high\|xhigh] [--power minimal\|low\|medium\|high\|xhigh] [--permission MODE] [--timeout-seconds N] [--label TEXT] [--max-parallel N] [--detach] [--failover] [--refresh] --json` | Run one headless task and return a stable JSON result; `--detach` returns the `run_id` at launch without waiting, `--failover` continues the task on the next account when this one hits its rate limit, `--prompt-file -` reads the prompt from stdin, `--label` names the run in `cdx runs`, `--max-parallel N` (default `CDX_MAX_RUNS`; unset, invalid, 0 or negative means no limit) refuses to start with `too_many_runs` when N runs are already running, `--kind` (default `assistant`) labels the run record and `code-review` adds a review report to its final payload |
+| `cdx run [session] --cwd PATH (--prompt-file PATH\|--prompt TEXT\|--prompt-file -) [--provider PROVIDER] [--model MODEL] [--kind assistant\|code-review\|retro] [--reasoning-effort minimal\|low\|medium\|high\|xhigh] [--power minimal\|low\|medium\|high\|xhigh] [--permission MODE] [--timeout-seconds N] [--label TEXT] [--max-parallel N] [--detach] [--failover] [--refresh] --json` | Run one headless task and return a stable JSON result; `--detach` returns the `run_id` at launch without waiting, `--failover` continues the task on the next account when this one hits its rate limit (with `--detach` too: the detached cdx child applies it and the run's `occupancies` record each move), `--prompt-file -` reads the prompt from stdin, `--label` names the run in `cdx runs`, `--max-parallel N` (default `CDX_MAX_RUNS`; unset, invalid, 0 or negative means no limit) refuses to start with `too_many_runs` when N runs are already running, `--kind` (default `assistant`) labels the run record and `code-review` adds a review report to its final payload |
 | `cdx run-report <run_id> --json` | Full report, transcript metadata, and final payload for a run; `final_message` is the run's last assistant message, read from Claude's `result` envelope or Codex's last `agent_message` (null when neither exists) |
 | `cdx run-status <run_id> --json` | Status of one run by id |
 | `cdx run-tail <run_id> [--lines N] --json` | Last lines of a run's own output, while it is still running or after it finished |

package/docs/features.md

@@ -29,7 +29,7 @@ The reason `cdx` exists: knowing, across every account you own, which one you ca
 ## Headless automation
 
 - **One task, one JSON result.** `cdx run` executes a prompt against a chosen or auto-selected session and returns a stable payload; `--detach` returns a `run_id` immediately.
-- **Survives a rate limit.** `cdx run --failover` notices that a run stopped because its account ran out, moves the task to the next account the ranking allows, and carries on — one `run_id` for the whole task, with every account it occupied listed in `cdx run-report`. A spent account is always confirmed against its own refreshed quota first, so a healthy account is never abandoned. From there two routes migrate a run: the provider said so in words cdx recognises, or — since that wording differs between an enterprise workspace out of credits, a personal plan hitting its 5-hour window, and Claude's own phrasing — simply that the account's quota is gone and the run failed. `cdx run-report` names which route applied. Exhausting every account reports `failover_exhausted`, which a caller can tell apart from the task itself failing.
+- **Survives a rate limit.** `cdx run --failover` notices that a run stopped because its account ran out, moves the task to the next account the ranking allows, and carries on — one `run_id` for the whole task, with every account it occupied listed in `cdx run-report`. A spent account is always confirmed against its own refreshed quota first, so a healthy account is never abandoned. From there two routes migrate a run: the provider said so in words cdx recognises, or — since that wording differs between an enterprise workspace out of credits, a personal plan hitting its 5-hour window, and Claude's own phrasing — simply that the account's quota is gone and the run failed. `cdx run-report` names which route applied. Exhausting every account reports `failover_exhausted`, which a caller can tell apart from the task itself failing. It combines with `--detach`: the detached cdx process supervises the run, applies the same rule, and records each move in the run registry; such a run always uses cdx's own detached child rather than the provider's background agent, which nothing would be watching.
 - **Native background delegation (opt-in).** With `CDX_EXPERIMENTAL_NATIVE_BG=1`, `cdx run --detach` hands the run to Claude Code's own background agents (`--bg`) instead of cdx's detached launcher. The run keeps its cdx `run_id`, closes out with its token usage and final answer read from the provider's own session transcript, and the parked session is stopped once its task is done. Off by default for one release while it settles; the in-house launcher is unchanged and is what every run takes otherwise. Codex keeps the in-house path while its `cloud`/`exec-server` surfaces are marked experimental.
 - **Observable runs.** `cdx run-status`, `cdx run-tail`, `cdx run-report`, and `cdx runs --since` follow a run while it happens and after it ends.
 - **Selection without launching.** `cdx select --provider ... --require-ready --json` answers "which session should this job use?" for orchestrators.

package/docs/sessions-and-notifications.md

@@ -38,8 +38,9 @@ visible on a lock screen; disable it per session with
 `cdx set <name> --notify-preview off`. Previews never read transcripts, and the
 command a permission request is about is never included.
 
-Both providers are subscribed to the same two hooks: `Stop` when a turn ends and
-`PermissionRequest` when one blocks on your approval. Claude Code is also
+Both providers are subscribed to the same two alerting hooks: `Stop` when a turn
+ends and `PermissionRequest` when one blocks on your approval, plus
+`UserPromptSubmit`, which raises no alert and only feeds the agent state below. Claude Code is also
 subscribed to `Notification`, for the "still waiting for you" states that no
 other hook reports; the permission notifications it also sends are dropped,
 because `PermissionRequest` already reported the same call immediately and by
@@ -71,6 +72,48 @@ disabled — cdx installs no hooks at all rather than asking you to approve
 something that could show you nothing. Headless `cdx run` never notifies: its
 caller already learns of completion from the return value.
 
+## Agent state
+
+Every hook event `cdx notify` receives also rewrites one small record for that
+session under `$CDX_HOME/state/agents/<session>.json`, whether alerts are on,
+muted or off. `cdx agents` lists them, so a dashboard, a chat agent or a
+terminal board can ask which sessions are working, waiting for you, done,
+failed or stopped by a usage limit without reading transcripts or terminals:
+
+```bash
+cdx set work1 --agent-state on   # hooks for state only, no desktop alerts
+cdx agents                       # table, waiting sessions first
+cdx agents --json                # the same for scripts
+cdx agents --max-age-hours 4     # drop records older than 4 hours (default 24)
+```
+
+Sessions with `--notify on` keep state already; `--agent-state on` is for
+sessions that want state without banners. It installs the same hooks, and it
+installs them even where no notification could be shown (an SSH login, a
+headless WSL), since a remote dashboard is exactly what watches those.
+
+| State | Set by |
+| --- | --- |
+| `working` | a prompt was submitted (`UserPromptSubmit`) |
+| `waiting` | a permission request, or Claude's idle or needs-input notification |
+| `done` | the turn ended (`Stop`) |
+| `failed` | the turn ended on a provider error (Claude's `StopFailure`); `reason` is the error class |
+| `limit` | that error says the account ran out and the account's own refreshed status agrees, the same two-signal rule as `cdx run --failover`; `reset_at` is the account's reset time when known |
+| `ended` | computed by `cdx agents`: the cdx process that launched the session is gone; `last_state` keeps what it was |
+
+`cdx agents --json` returns `{"ok": true, "action": "agents", "max_age_hours": 24,
+"agents": [...]}`, each entry carrying `session`, `provider`, `cwd`, `project`,
+`state`, `reason`, `prompt`, `reset_at`, `pid` and `updated_at` (ISO 8601, UTC).
+`prompt` is the head of the last prompt, at most 120 characters, and only for
+sessions with `--notify-preview on`; otherwise it is `null`. Records older than
+the maximum age are deleted when listed.
+
+A waiting session stays `waiting` until its next prompt or the end of the turn:
+cdx does not subscribe to every tool call to notice that you answered. A Codex
+profile whose cdx plugin was installed before this release keeps its old hooks
+(no `working` state) until the plugin is reinstalled with `cdx set <name>
+--notify off`, a launch, then `--notify on` and another launch.
+
 Use `cdx ready` when every useful assistant is cooling down and you want your terminal back. cdx picks the next known reset, registers a native OS notification, and exits immediately. If no future reset is known, it exits successfully and explains that no notification was scheduled.
 
 ```bash

package/package.json

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

package/pyproject.toml

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

package/src/agent_notify.py

@@ -15,10 +15,12 @@ import re
 import shutil
 import subprocess
 
+from . import agent_state
 from .config import get_cdx_home
 from .fs_utils import atomic_write
 from .notify import notification_channel, send_desktop_notification
 from .tray_alerts import alerts_enabled
+from .tray_defaults import alerts_default
 from .tray_events import publish
 
 # Set on the provider process at launch; the hook runs as its child and inherits both.
@@ -121,6 +123,10 @@ def _is_reportable(payload, event):
     reports exactly — `permission_prompt` duplicates PermissionRequest — or an
     internal state the user has no action to take on.
     """
+    if event == "userpromptsubmit":
+        # Subscribed for the agent state only; a prompt the user just typed is
+        # not news to them.
+        return False
     if event != "notification":
         return True
     kind = str(payload.get("notification_type") or "").lower()
@@ -291,8 +297,9 @@ def handle_notify(rest, ctx):
         # call being asked about, so a stray line would allow or deny it. The
         # notification paths below print nothing; this is the statement of why
         # they must not start.
+        _record_state(ctx, payload, env)
         composed = compose_notification(payload, env, ctx.get("cwd"))
-        if composed:
+        if composed and _alerts_wanted(ctx, env.get(SESSION_ENV)):
             # Muted stops the banner, not the record: the event still reaches a
             # running tray so the menu can show what was missed, and the direct
             # path stays quiet too — otherwise quitting the tray would un-mute.
@@ -313,6 +320,43 @@ def handle_notify(rest, ctx):
     return 0
 
 
+def _record_state(ctx, payload, env):
+    """Keep this event as the session's state, before and apart from any alert.
+
+    Recorded whether alerts are on, muted or off: a dashboard asking which
+    session waits for its user must not go blind because the banner was muted.
+    Its own guard, so a failed write never costs the alert either.
+    """
+    try:
+        event = hook_event(payload)
+        prompt = ""
+        if event == "userpromptsubmit" and env.get(PREVIEW_ENV) == "1":
+            prompt = _notification_text(payload.get("prompt"), agent_state._PROMPT_LIMIT)
+        directory = payload.get("cwd") or payload.get("workspace") or ctx.get("cwd") or os.getcwd()
+        agent_state.record(
+            ctx, env.get(SESSION_ENV), payload, event, error_class(payload), directory, env, prompt=prompt,
+        )
+    except Exception:  # noqa: BLE001 - the caller is an agent turn
+        pass
+
+
+def _alerts_wanted(ctx, name):
+    """False only for a session whose hooks exist for its state alone.
+
+    `--agent-state on` installs the same hooks as `--notify on`, so without this
+    a session that asked for state only would start raising desktop alerts.
+    Anything unreadable keeps the alert: that was the behaviour before state.
+    """
+    service = ctx.get("service") or {}
+    try:
+        session = service["get_session"](name)
+    except Exception:  # noqa: BLE001 - a missing store is not a reason to drop alerts
+        return True
+    if not agent_state.agent_state_enabled(session):
+        return True
+    return notifications_enabled(session) or alerts_default(service["base_dir"])
+
+
 def launch_notify_env(session, enabled, env=None):
     """Env the provider is launched with, carrying who we are and privacy settings.
 
@@ -325,7 +369,7 @@ def launch_notify_env(session, enabled, env=None):
     running tray that never receives an alert, with nothing reporting an error.
     """
     env = os.environ if env is None else env
-    values = {SESSION_ENV: session["name"], "CDX_HOME": get_cdx_home(env)}
+    values = {SESSION_ENV: session["name"], "CDX_HOME": get_cdx_home(env), agent_state.PID_ENV: str(os.getpid())}
     if enabled and (session.get("launch") or {}).get("notify_preview") is True:
         values[PREVIEW_ENV] = "1"
     return values
@@ -343,7 +387,7 @@ def notifications_enabled(session):
     return launch.get("notify") is True
 
 
-def provision(auth_home, provider, enabled, env=None, spawn_sync=None, base_dir=None):
+def provision(auth_home, provider, enabled, env=None, spawn_sync=None, base_dir=None, keep_state=False):
     """Install or remove cdx's notification hooks in this session's own home.
 
     Idempotent, so an existing session picks the hooks up on its next launch and
@@ -356,7 +400,9 @@ def provision(auth_home, provider, enabled, env=None, spawn_sync=None, base_dir=
     anywhere under `CODEX_HOME` is never looked at.
     """
     env = env or os.environ
-    if enabled and not notification_channel(env):
+    # `keep_state` needs the hooks whether or not anything can be shown here:
+    # a session driven over SSH is exactly the one a remote dashboard watches.
+    if enabled and not keep_state and not notification_channel(env):
         # Nothing could be delivered on this host (an SSH login, say), so
         # installing a hook would only buy an approval prompt for a feature that
         # shows nothing. Removing existing hooks is no better: Codex would ask to
@@ -458,7 +504,7 @@ def _write_codex_plugin(auth_home, command, base_dir=None):
         os.path.join(root, "hooks", "cdx-hooks.json"): {
             "hooks": {
                 event: [{"hooks": [{"type": "command", "command": f"{command} {HOOK_ARG}"}]}]
-                for event in ("Stop", "PermissionRequest")
+                for event in ("UserPromptSubmit", "Stop", "PermissionRequest")
             },
         },
     }
@@ -509,7 +555,9 @@ def _apply_hooks(path, enabled, command):
     # StopFailure is Claude-only: Codex documents no equivalent, so a turn its
     # provider kills stays silent there and the documentation says so rather
     # than implying a parity that does not exist.
-    for event in ("Stop", "StopFailure", "Notification", "PermissionRequest"):
+    # UserPromptSubmit is there for the agent state only: it is what says a
+    # session went back to work, and `cdx notify` raises no alert for it.
+    for event in ("UserPromptSubmit", "Stop", "StopFailure", "Notification", "PermissionRequest"):
         # Rebuilt from whatever is there minus our own entry, so user-authored
         # hooks on the same event survive both installing and removing.
         entries = [entry for entry in hooks.get(event, []) if not _is_ours(entry)]

package/src/agent_state.py

@@ -0,0 +1,197 @@
+"""What each cdx session's agent is doing right now, kept from its hook events.
+
+`cdx notify` hears every hook event and used to forget it once the alert was
+out. Here the same event also rewrites one small record per session, so a
+dashboard, a chat agent or a terminal board can ask `cdx agents --json` which
+sessions are working, waiting for their user, done, failed or out of quota
+without parsing transcripts or terminals.
+
+One file per session rather than one shared file: two sessions finishing in
+the same instant then never race over a single document.
+"""
+
+import json
+import os
+from datetime import datetime, timedelta, timezone
+
+from .errors import CdxError
+from .fs_utils import atomic_write
+from .run_failover import _mentions_exhaustion, status_confirms_exhaustion
+from .session_helpers import _process_is_running
+
+AGENTS_USAGE = "Usage: cdx agents [--max-age-hours N] [--json]"
+DEFAULT_MAX_AGE_HOURS = 24
+# Set on the provider at launch: the cdx process that waits on it. The hook is
+# a grandchild at best (Claude Code runs it through a shell), so its own parent
+# is no proof the agent is alive; the launcher is.
+PID_ENV = "CDX_AGENT_PID"
+_PROMPT_LIMIT = 120
+_WAITING_NOTIFICATIONS = {"", "idle_prompt", "agent_needs_input", "permission_prompt"}
+
+
+def agent_state_enabled(session):
+    """Whether this session asked for its hooks to keep state, alerts or not."""
+    return ((session or {}).get("launch") or {}).get("agent_state") is True
+
+
+def state_dir(base_dir):
+    return os.path.join(base_dir, "state", "agents")
+
+
+def classify(payload, event, error_class):
+    """(state, reason) for this event, or None when it changes nothing."""
+    if event == "userpromptsubmit":
+        return "working", None
+    if event == "permissionrequest":
+        tool = payload.get("tool_name")
+        return "waiting", f"permission ({tool})" if isinstance(tool, str) and tool else "permission"
+    if event == "notification":
+        kind = str(payload.get("notification_type") or "").lower()
+        return ("waiting", kind or "notification") if kind in _WAITING_NOTIFICATIONS else None
+    if event in ("stop", "agentturncomplete"):
+        return "done", None
+    if event == "stopfailure":
+        return "failed", error_class or "turn failed"
+    return None
+
+
+def confirmed_limit(ctx, name, payload, error_class):
+    """The status row proving a usage limit, or None.
+
+    The run_failover rule, both halves: the provider has to call the failure
+    exhaustion in its own words, and the account's own status has to agree. A
+    turn that merely failed, or an account whose status cannot be read, stays
+    `failed`; marking a healthy session `limit` would send someone to wait out a
+    reset that is not coming.
+    """
+    message = payload.get("error_message")
+    if not _mentions_exhaustion([error_class] + ([message] if isinstance(message, str) else [])):
+        return None
+    # Imported here: commands sit above this module, and the refresh-then-cache
+    # read is theirs to own.
+    from .commands.runs import _status_row_for
+    row = _status_row_for(ctx, name)
+    return row if status_confirms_exhaustion(row) else None
+
+
+def record(ctx, name, payload, event, error_class, cwd, env, prompt=None):
+    """Rewrite this session's record for one hook event. Writes nothing to stdout."""
+    base_dir = (ctx.get("service") or {}).get("base_dir")
+    # The name comes from the environment; it must stay a plain file name.
+    if not base_dir or not name or os.path.basename(name) != name or name in (".", ".."):
+        return None
+    classified = classify(payload, event, error_class)
+    if not classified:
+        return None
+    state, reason = classified
+    path = os.path.join(state_dir(base_dir), f"{name}.json")
+    current = _read(path) or {}
+    if state == "working":
+        # Only under the preview opt-in, like any other free text a hook carries.
+        current["prompt"] = prompt or None
+    current.setdefault("prompt", None)
+    reset_at = None
+    if state == "failed":
+        row = confirmed_limit(ctx, name, payload, error_class)
+        if row is not None:
+            state, reset_at = "limit", row.get("reset_at")
+    provider = current.get("provider")
+    get_session = (ctx.get("service") or {}).get("get_session")
+    if get_session:
+        provider = (get_session(name) or {}).get("provider") or provider
+    pid = env.get(PID_ENV)
+    current.update({
+        "session": name,
+        "provider": provider,
+        "cwd": str(cwd),
+        "project": os.path.basename(str(cwd).rstrip("/\\")) or str(cwd),
+        "state": state,
+        "reason": reason,
+        "reset_at": reset_at,
+        "pid": int(pid) if pid and pid.isdigit() else current.get("pid"),
+        "updated_at": datetime.now(timezone.utc).isoformat(),
+    })
+    atomic_write(path, json.dumps(current, indent=2) + "\n", mode=0o600)
+    return current
+
+
+def _read(path):
+    try:
+        with open(path, encoding="utf-8") as handle:
+            document = json.load(handle)
+    except (OSError, ValueError):
+        return None
+    return document if isinstance(document, dict) else None
+
+
+def list_agents(base_dir, max_age_hours=DEFAULT_MAX_AGE_HOURS, now=None, is_running=_process_is_running):
+    """Live records, waiting first then newest; stale ones are deleted on the way."""
+    now = now or datetime.now(timezone.utc)
+    cutoff = now - timedelta(hours=max_age_hours)
+    directory = state_dir(base_dir)
+    try:
+        names = sorted(os.listdir(directory))
+    except OSError:
+        return []
+    agents = []
+    for file_name in names:
+        if not file_name.endswith(".json"):
+            continue
+        path = os.path.join(directory, file_name)
+        entry = _read(path)
+        try:
+            updated = datetime.fromisoformat(entry["updated_at"])
+        except (TypeError, KeyError, ValueError):
+            updated = None
+        if updated is None or updated.tzinfo is None or updated < cutoff:
+            try:
+                os.remove(path)
+            except OSError:
+                pass
+            continue
+        if entry.get("pid") and not is_running(entry["pid"]):
+            entry["last_state"], entry["state"] = entry.get("state"), "ended"
+        agents.append(entry)
+    agents.sort(key=lambda entry: entry["updated_at"], reverse=True)
+    agents.sort(key=lambda entry: entry.get("state") != "waiting")
+    return agents
+
+
+def handle_agents(rest, ctx):
+    # Imported here: this module is loaded by the hook path through
+    # agent_notify, and the CLI helpers import provider_runtime, which imports
+    # agent_notify back.
+    from .cli_args import _parse_flag_args
+    from .cli_helpers import _json_success, _write_json
+    from .cli_render import _pad_table
+
+    parsed = _parse_flag_args(rest, {
+        "--max-age-hours": {"key": "max_age_hours", "type": "str", "default": None},
+        "--json": {"key": "json", "type": "bool", "default": False},
+    }, AGENTS_USAGE)
+    max_age = DEFAULT_MAX_AGE_HOURS
+    if parsed["max_age_hours"] is not None:
+        try:
+            max_age = int(parsed["max_age_hours"])
+        except ValueError:
+            max_age = 0
+        if max_age < 1:
+            raise CdxError(AGENTS_USAGE)
+    agents = list_agents(ctx["service"]["base_dir"], max_age)
+    if parsed["json"]:
+        _write_json(ctx, _json_success("agents", "Agents loaded.", agents=agents, max_age_hours=max_age))
+        return 0
+    if not agents:
+        ctx["out"]("No agent state recorded. Turn it on with: cdx set <name> --agent-state on\n")
+        return 0
+    rows = [["SESSION", "STATE", "PROJECT", "REASON", "UPDATED"]]
+    for entry in agents:
+        rows.append([
+            entry.get("session") or "",
+            entry.get("state") or "",
+            entry.get("project") or "",
+            entry.get("reason") or "",
+            entry.get("updated_at") or "",
+        ])
+    ctx["out"](_pad_table(rows) + "\n")
+    return 0

package/src/cli.py

@@ -6,6 +6,7 @@ import sys
 from datetime import datetime, timezone
 
 from .agent_notify import handle_notify
+from .agent_state import handle_agents
 from .cli_args import SET_USAGE
 from .cli_commands import (
     API_SCHEMA_VERSION,
@@ -153,6 +154,7 @@ __all__ = [
 _COMMAND_HANDLERS = {
     "auth": handle_auth,
     "add": handle_add,
+    "agents": handle_agents,
     "cp": handle_copy,
     "clean": handle_clean,
     "config": handle_config,
@@ -239,6 +241,7 @@ def _print_help(use_color=False):
         f"  {_style('cdx status --small|-s [--refresh|--cached] [--timeout SECONDS]', '36', use_color)}",
         f"  {_style('cdx status <name> [--json] [--refresh|--cached] [--timeout SECONDS]', '36', use_color)}",
         f"  {_style('cdx next [--json] [--refresh]', '36', use_color)}",
+        f"  {_style('cdx agents [--max-age-hours N] [--json]', '36', use_color)}",
         f"  {_style('cdx reset <name> [--yes] [--json]', '36', use_color)}",
         f"  {_style('cdx auth refresh <name|all> [--json]', '36', use_color)}",
         f"  {_style('cdx select --provider PROVIDER [--min-reasoning-effort minimal|low|medium|high|xhigh] [--min-power minimal|low|medium|high|xhigh] [--require-ready] [--refresh] --json', '36', use_color)}",

package/src/cli_args.py

@@ -33,8 +33,8 @@ CONTEXT_USAGE = "Usage: cdx context show|path|init|edit|clear|set|append [text..
 MEMORY_USAGE = "Usage: cdx memory [--global|--project NAME_OR_PATH] [show|view|path|init|edit|clear|set|append|list] [text...] [--json]"
 HANDOFF_USAGE = "Usage: cdx handoff <name> [--json] | cdx handoff <source> <target> [--source-conversation ID | --source-native-transcript PATH | --source-transcript PATH] [--json]"
 LABEL_USAGE = "Usage: cdx label <name> <label> [--json] | cdx label <name> --clear [--json]"
-SET_USAGE = "Usage: cdx set <name>|--sessions all|a,b|--provider PROVIDER [--power minimal|low|medium|high|xhigh] [--permission review|default|auto|full] [--fast on|off] [--rtk on|off] [--logics on|off] [--notify on|off] [--notify-preview on|off] [--scrub-env on|off] [--shared-memory on|off] [--retro on|off] [--policy use|ask-first|never] [--model MODEL] [--fallback-model MODEL[,MODEL...]] [--budget USD] [--extra-args 'ARGS'] [--priority 0..100] [--json]"
-UNSET_USAGE = "Usage: cdx unset <name>|--sessions all|a,b|--provider PROVIDER (--power|--reasoning-effort|--permission|--fast|--rtk|--logics|--notify|--notify-preview|--scrub-env|--shared-memory|--retro|--policy|--model|--fallback-model|--budget|--extra-args|--priority|--all) [--json]"
+SET_USAGE = "Usage: cdx set <name>|--sessions all|a,b|--provider PROVIDER [--power minimal|low|medium|high|xhigh] [--permission review|default|auto|full] [--fast on|off] [--rtk on|off] [--logics on|off] [--notify on|off] [--agent-state on|off] [--notify-preview on|off] [--scrub-env on|off] [--shared-memory on|off] [--retro on|off] [--policy use|ask-first|never] [--model MODEL] [--fallback-model MODEL[,MODEL...]] [--budget USD] [--extra-args 'ARGS'] [--priority 0..100] [--json]"
+UNSET_USAGE = "Usage: cdx unset <name>|--sessions all|a,b|--provider PROVIDER (--power|--reasoning-effort|--permission|--fast|--rtk|--logics|--notify|--agent-state|--notify-preview|--scrub-env|--shared-memory|--retro|--policy|--model|--fallback-model|--budget|--extra-args|--priority|--all) [--json]"
 SETTING_ALIAS_USAGE = "Usage: cdx power|perm|fast|model <name|all|provider:PROVIDER|a,b> <value|default> [--json]"
 CONFIG_USAGE = "Usage: cdx config <name> [--json]"
 CONFIGS_USAGE = "Usage: cdx configs [--json]"
@@ -53,7 +53,6 @@ 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."
 RUN_CWD_REQUIRED = "cdx run: --cwd PATH is required."
 RUN_PROMPT_SOURCE_REQUIRED = "cdx run: specify exactly one prompt source: --prompt TEXT or --prompt-file PATH."
-RUN_DETACH_FAILOVER_CONFLICT = "cdx run: --failover needs to watch the run, which --detach gives up."
 RUN_KIND_VALUES = ("assistant", "code-review", "retro")
 # Aliases of the shared definitions in config, kept only so the existing
 # RUN_* spellings in this module keep reading naturally. They are references,
@@ -275,6 +274,7 @@ def _parse_set_args(args):
         "--rtk": {"key": "rtk", "type": "str", "default": None, "transform": _on_off("rtk")},
         "--logics": {"key": "logics", "type": "str", "default": None, "transform": _on_off("logics")},
         "--notify": {"key": "notify", "type": "str", "default": None, "transform": _on_off("notify")},
+        "--agent-state": {"key": "agent_state", "type": "str", "default": None, "transform": _on_off("agent state")},
         "--notify-preview": {"key": "notify_preview", "type": "str", "default": None, "transform": _on_off("notify preview")},
         "--scrub-env": {"key": "scrub_env", "type": "str", "default": None, "transform": _on_off("scrub env")},
         "--shared-memory": {"key": "shared_memory", "type": "str", "default": None, "transform": _on_off("shared memory")},
@@ -301,7 +301,7 @@ def _parse_set_args(args):
         raise CdxError(SET_USAGE)
     settings = {
         key: parsed[key]
-        for key in ("power", "permission", "fast", "rtk", "logics", "notify", "notify_preview", "scrub_env", "shared_memory", "retro", "model", "fallback_model", "budget", "extra_args", "priority", "policy")
+        for key in ("power", "permission", "fast", "rtk", "logics", "notify", "agent_state", "notify_preview", "scrub_env", "shared_memory", "retro", "model", "fallback_model", "budget", "extra_args", "priority", "policy")
         if parsed[key] is not None
     }
     if not settings:
@@ -324,6 +324,7 @@ def _parse_unset_args(args):
         "--rtk": {"key": "rtk", "type": "bool", "default": False},
         "--logics": {"key": "logics", "type": "bool", "default": False},
         "--notify": {"key": "notify", "type": "bool", "default": False},
+        "--agent-state": {"key": "agent_state", "type": "bool", "default": False},
         "--notify-preview": {"key": "notify_preview", "type": "bool", "default": False},
         "--scrub-env": {"key": "scrub_env", "type": "bool", "default": False},
         "--shared-memory": {"key": "shared_memory", "type": "bool", "default": False},
@@ -350,7 +351,7 @@ def _parse_unset_args(args):
     if not parsed["names"] and not parsed["sessions"] and not parsed["provider"]:
         raise CdxError(UNSET_USAGE)
     _UNSET_KEYS = (
-        "power", "reasoning_effort", "permission", "fast", "rtk", "logics", "notify", "notify_preview", "scrub_env", "shared_memory", "retro",
+        "power", "reasoning_effort", "permission", "fast", "rtk", "logics", "notify", "agent_state", "notify_preview", "scrub_env", "shared_memory", "retro",
         "model", "fallback_model", "budget", "extra_args", "priority", "policy",
     )
     keys = list(_UNSET_KEYS) if parsed["all"] else [key for key in _UNSET_KEYS if parsed[key]]
@@ -506,11 +507,6 @@ def cdx_schema():
                 "arguments": ["--prompt-file", "--prompt"],
                 "reason": "Exactly one prompt source.",
             },
-            {
-                "command": "run",
-                "arguments": ["--detach", "--failover"],
-                "reason": "Failover has to watch the run to react to a rate limit; --detach stops watching.",
-            },
         ],
         # Not mutually exclusive: both may be given, and cdx accepts them when
         # they agree. A caller generating validation from `mutually_exclusive`
@@ -694,12 +690,6 @@ def _parse_run_args(args):
             code=ARG_CODE_MUTUALLY_EXCLUSIVE,
             arguments=["--prompt-file", "--prompt"],
         )
-    if parsed["detach"] and parsed["failover"]:
-        raise CdxArgumentError(
-            RUN_DETACH_FAILOVER_CONFLICT,
-            code=ARG_CODE_MUTUALLY_EXCLUSIVE,
-            arguments=["--detach", "--failover"],
-        )
     if not parsed["prompt_file"] and not parsed["prompt"]:
         raise CdxArgumentError(
             RUN_PROMPT_SOURCE_REQUIRED,

package/src/cli_helpers.py

@@ -312,6 +312,7 @@ def _format_launch_config(session, use_color=False):
         ("rtk", "RTK"),
         ("logics", "Logics"),
         ("notify", "Agent alerts"),
+        ("agent_state", "Agent state"),
         ("notify_preview", "Response preview"),
         ("scrub_env", "Scrub agent env"),
         ("shared_memory", "Shared memory"),
@@ -343,14 +344,14 @@ def _format_launch_settings_hint(name="<name>"):
     )
 
 def _format_launch_setting_value(launch, key, use_color=False):
-    if key in ("fast", "rtk", "logics", "notify", "notify_preview", "scrub_env", "shared_memory", "retro"):
+    if key in ("fast", "rtk", "logics", "notify", "agent_state", "notify_preview", "scrub_env", "shared_memory", "retro"):
         if launch.get(key) is True:
             return _style("on", "32", use_color)
         if launch.get(key) is False:
             return _style("off", "2", use_color)
         if key == "logics":
             return _dim("auto", use_color)
-        if key in ("notify", "notify_preview", "scrub_env", "shared_memory", "retro"):
+        if key in ("notify", "agent_state", "notify_preview", "scrub_env", "shared_memory", "retro"):
             return _style("off", "2", use_color)
         return _dim("default", use_color)
     value = launch.get(key)

package/src/commands/launch.py

@@ -8,6 +8,7 @@ import shlex
 
 from .. import retro, shared_memory
 from ..agent_notify import notifications_enabled, provision, supports_agent_alerts
+from ..agent_state import agent_state_enabled
 from ..cli_args import CAN_RESUME_USAGE, HANDOFF_USAGE, RESUME_USAGE, _parse_json_flag, _pop_value_flag
 from ..cli_helpers import (
     API_SCHEMA_VERSION,
@@ -301,13 +302,15 @@ def handle_launch(command, ctx, initial_prompt=None, resume=False, force_json=No
         ctx["out"](f"{_info(message, ctx['use_color'])}\n")
         _write_update_notice(ctx)
     alerts_allowed = _notification_provisioning_enabled(session, ctx, json_flag)
+    keep_state = agent_state_enabled(session)
     installed = provision(
         _get_auth_home(session),
         session["provider"],
-        alerts_allowed,
+        alerts_allowed or keep_state,
         ctx.get("env"),
         spawn_sync=ctx.get("spawn_sync"),
         base_dir=ctx["service"]["base_dir"],
+        keep_state=keep_state,
     )
     if installed and not json_flag:
         notice = f"Notification hooks installed for {session['name']}"

package/src/commands/runs.py

@@ -204,6 +204,10 @@ def _detached_child_argv(parsed, prompt_path, session_name, cwd):
         argv += ["--reasoning-effort", str(parsed["reasoning_effort"])]
     if parsed.get("timeout_seconds"):
         argv += ["--timeout-seconds", str(parsed["timeout_seconds"])]
+    # The child is the supervisor: it watches the run like any blocking one, so
+    # it applies the failover rule and records each move in the registry.
+    if parsed.get("failover"):
+        argv.append("--failover")
     argv.append("--json")
     return argv
 
@@ -637,7 +641,9 @@ def handle_run(rest, ctx):
             # agent and report on it; fall back to the in-house launcher
             # otherwise, and whenever the provider declines to start one.
             launch = None
-            if supports_native_background(
+            # A provider's own background agent has no cdx process watching it,
+            # so nothing could fail it over; --failover keeps the in-house child.
+            if not parsed.get("failover") and supports_native_background(
                 run_session.get("provider"),
                 env=ctx.get("env"),
                 spawn_sync=ctx.get("spawn_text"),

package/src/provider_runtime.py

@@ -12,6 +12,7 @@ import uuid
 from datetime import datetime, timezone
 
 from .agent_notify import launch_notify_env, notifications_enabled
+from .agent_state import agent_state_enabled
 from .claude_credentials import peek_keychain_credentials, read_claude_login_file
 from .claude_usage import _clean_oauth_token, _decode_jwt_claims, _secure_storage_overrides, claude_profile_store_dir
 from .codex_usage import codex_auth_lock, diagnostic_needs_codex_login, fetch_codex_rate_limit_diagnostic
@@ -716,7 +717,7 @@ def _build_launch_spec(session, cwd=None, env_override=None, initial_prompt=None
     for key, value in _shared_tool_cache_overrides(env).items():
         env.setdefault(key, value)
     _shared_rtk_history(env)
-    env.update(launch_notify_env(session, notifications_enabled(session)))
+    env.update(launch_notify_env(session, notifications_enabled(session) or agent_state_enabled(session)))
     env.update(_scrub_env(session))
     preference_args = _launch_preference_args(session, env=env)
     if session["provider"] == PROVIDER_CLAUDE:

package/src/session_helpers.py

@@ -24,6 +24,7 @@ MAX_SESSION_NAME_LENGTH = 64
 
 RESERVED_SESSION_NAMES = {
     "add",
+    "agents",
     "can-resume",
     "clean",
     "context",

package/src/session_service.py

@@ -148,7 +148,7 @@ def _seed_codex_auth_from_global(auth_home, env=None):
     return True
 
 
-_ON_OFF_SETTINGS = {"fast": "fast", "rtk": "rtk", "logics": "logics", "notify": "notify", "notify_preview": "notify preview", "scrub_env": "scrub env", "shared_memory": "shared memory", "retro": "retro"}
+_ON_OFF_SETTINGS = {"fast": "fast", "rtk": "rtk", "logics": "logics", "notify": "notify", "agent_state": "agent state", "notify_preview": "notify preview", "scrub_env": "scrub env", "shared_memory": "shared memory", "retro": "retro"}
 
 
 def _has_control_chars(text):
@@ -323,7 +323,7 @@ def unset_launch_settings(store, name, keys):
     if not keys:
         raise CdxError("At least one launch setting is required.")
     allowed = {
-        "power", "reasoning_effort", "reasoningEffort", "permission", "fast", "rtk", "logics", "notify", "notify_preview",
+        "power", "reasoning_effort", "reasoningEffort", "permission", "fast", "rtk", "logics", "notify", "agent_state", "notify_preview",
         "scrub_env", "shared_memory", "retro", "model", "fallback_model", "budget", "extra_args", "priority", "policy",
     }
     unknown = [key for key in keys if key not in allowed]