cdx-manager 0.22.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.22.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.22.0
+0.24.0

package/changelogs/CHANGELOGS_0_23_0.md

@@ -0,0 +1,19 @@
+# CDX Manager 0.23.0
+
+This release gives external orchestrators a stable way to read runs, live sessions and profile locations, so they no longer need to scan processes, parse provider output or rely on cdx's directory layout.
+
+## Runs
+
+- `cdx runs --running --json` returns every run still in progress, without the `--limit` cap, so a concurrency check always sees the full count.
+- `cdx run-report` now includes `final_message`: the run's last assistant message, read from Claude's result or Codex's last agent message.
+- The accepted run `kind` values are documented with `cdx runs`; `cdx schema --json` remains their source.
+
+## Sessions and profiles
+
+- `cdx sessions --json` lists interactive sessions launched through cdx that are still running, with their process id, provider, working directory, start time and conversation id.
+- `cdx sessions --all --json` adds idle accounts. Each row includes `profile_dir` and `transcripts_dir`; the credential directory stays hidden.
+
+## Resume
+
+- `cdx can-resume <name> --conversation <id>` checks one exact conversation on Claude or Codex.
+- `cdx resume <name> --conversation <id>` reopens that conversation. A missing conversation is refused with `conversation_not_found` rather than replaced by the most recent one.

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

@@ -551,6 +551,28 @@
         "x86_64-pc-windows-msvc": "65cb725a2ae55350b8d9500f4293cd52e709ee017c999d65de9a1e12b472f7ed",
         "x86_64-unknown-linux-musl": "6ff5479d7d57f329e76ad633e963e0d45f059d28004a3777f406b5bdd0713abe"
       }
+    },
+    "v0.22.0": {
+      "github_tarball_sha256": "06d623fad9ee339e6810792d94b925e3a27f62612b5ac015e8fb236093417bf1",
+      "github_zip_sha256": "fbfcc2748282f60968bbfb4127f97b2866890e1bf54e5d92e2b81e5526c92f6d",
+      "tray_assets": {
+        "aarch64-apple-darwin": "57ec5cec2876eecf62397b66f78cbb5028583e06deedab79b2af17bafc7a8d05",
+        "aarch64-unknown-linux-musl": "948110290f030caafe46eebf2db6e5565fc48e5fc4983a0c70d946336f39ec9e",
+        "x86_64-apple-darwin": "bb873f982b4af1a3cc53235e615fad2e2be8265defea0def0fde463467fa3495",
+        "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,12 +24,13 @@
 | `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> [--json]` | Resume the provider-native conversation for a session using the named command form |
-| `cdx can-resume <name> [--json]` | Check whether a session supports native resume without launching the provider |
+| `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 |
+| `cdx can-resume <name> [--conversation <id>] [--json]` | Check whether a session supports native resume without launching the provider; `--conversation` checks that exact conversation and reports `resumable: false` with `conversation_not_found` instead of falling back to the most recent one |
+| `cdx sessions [--all] --json` | Interactive sessions launched through cdx that are still running (`session`, `provider`, `pid`, `cwd`, `started_at`, `conversation_id`, `profile_dir`, `transcripts_dir`); `--all` adds idle enabled accounts so any account's directories can be resolved |
 | `cdx context show\|path\|init\|edit\|clear\|set\|append [text...] [--json]` | Manage the shared Markdown context for the current workspace |
 | `cdx memory [--global\|--project NAME_OR_PATH] [show\|view\|path\|init\|edit\|clear\|set\|append\|list] [text...] [--json]` | Manage explicit user-controlled memory for the current workspace, global scope, or a named/path project |
 | `cdx handoff <name> [--json]` | Reuse the prepared entry for this target/workspace, or use explicitly labelled notes-only recovery if none exists; launch unless `--json` |
@@ -49,14 +50,15 @@
 | `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-report <run_id> --json` | Full report, transcript metadata, and final payload for a run |
+| `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 |
-| `cdx runs [--limit N] [--since 7d\|today\|DATE] --json` | List recent runs; `--since` returns every run completed after the cursor and ignores `--limit` |
+| `cdx runs [--limit N] [--since 7d\|today\|DATE] [--running] --json` | List recent runs; `--since` returns every run completed after the cursor and ignores `--limit`; `--running` returns every run still running, uncapped. A run's `kind` is one of the values `cdx schema --json` lists under `enums.kind` |
 | `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] [--by session\|project\|model] [--json]` | Aggregate launch counts, duration, and known token usage by session, for headless and interactive runs alike. `--by project` groups runs by launch folder (labelled by the shortest trailing part that tells folders apart; `project` in JSON holds the full path), `--by model` by the model that served them (same totals, same pricing; default `session`). PROV. lists every provider a row saw, such as `claude+codex`. Without a session filter it also prints what rtk saved over the period (`rtk` in JSON), read with `rtk gain` from `RTK_DB_PATH` when set, else the shared history, and the older per-profile ones. |
 | `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; Claude rows also report the auth type (`setup-token` or `full-login`) in a TYPE column and as `auth_type` in JSON. |

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.22.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.22.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,
@@ -50,6 +51,7 @@ from .cli_commands import (
     handle_runs,
     handle_schema,
     handle_select,
+    handle_sessions,
     handle_set,
     handle_stats,
     handle_status,
@@ -152,6 +154,7 @@ __all__ = [
 _COMMAND_HANDLERS = {
     "auth": handle_auth,
     "add": handle_add,
+    "agents": handle_agents,
     "cp": handle_copy,
     "clean": handle_clean,
     "config": handle_config,
@@ -187,6 +190,7 @@ _COMMAND_HANDLERS = {
     "runs": handle_runs,
     "schema": handle_schema,
     "select": handle_select,
+    "sessions": handle_sessions,
     "set": handle_set,
     "stats": handle_stats,
     "status": handle_status,
@@ -237,13 +241,15 @@ 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)}",
         f"  {_style('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 review|default|auto|full|workspace-write|read-only|danger-full-access] [--timeout-seconds N] [--label TEXT] [--max-parallel N] [--detach] [--failover] [--refresh] --json', '36', use_color)}",
-        f"  {_style('cdx runs [--limit N] [--since 7d|today|DATE] --json', '36', use_color)}",
+        f"  {_style('cdx runs [--limit N] [--since 7d|today|DATE] [--running] --json', '36', use_color)}",
         f"  {_style('cdx run-status <run_id> --json', '36', use_color)}",
         f"  {_style('cdx run-report <run_id> --json', '36', use_color)}",
+        f"  {_style('cdx sessions [--all] --json', '36', use_color)}",
         f"  {_style('cdx run-tail <run_id> [--lines N] --json', '36', use_color)}",
         f"  {_style('cdx schema --json', '36', use_color)}",
         f"  {_style('cdx context show|path|init|edit|clear|set|append [text...] [--json]', '36', use_color)}",
@@ -257,8 +263,8 @@ def _print_help(use_color=False):
         f"  {_style('cdx history [name] [--limit N] [--summary] [--since 7d|today|DATE] [--from DATE] [--to DATE] [--json]', '36', use_color)}",
         f"  {_style('cdx stats [name] [--since 7d|today|DATE] [--from DATE] [--to DATE] [--by session|project|model] [--json]', '36', use_color)}",
         f"  {_style('cdx last [--json]', '36', use_color)}",
-        f"  {_style('cdx resume <name> [--json]', '36', use_color)}",
-        f"  {_style('cdx can-resume <name> [--json]', '36', use_color)}",
+        f"  {_style('cdx resume <name> [--conversation <id>] [--json]', '36', use_color)}",
+        f"  {_style('cdx can-resume <name> [--conversation <id>] [--json]', '36', use_color)}",
         f"  {_style('cdx rescue [<session>] [--to <target>] [--yes] [--dry-run] [--json]', '36', use_color)}",
         f"  {_style('cdx retro [--limit N] [--json]', '36', use_color)}",
         f"  {_style('cdx handoff <name> [--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]"
@@ -42,8 +42,9 @@ HISTORY_USAGE = "Usage: cdx history [name] [--limit N] [--summary] [--since 7d|t
 STATS_USAGE = "Usage: cdx stats [name] [--since 7d|today|DATE] [--from DATE] [--to DATE] [--by session|project|model] [--json]"
 STATS_GROUPS = ("session", "project", "model")
 LAST_USAGE = "Usage: cdx last [--json]"
-RESUME_USAGE = "Usage: cdx resume <name> [--json]"
-CAN_RESUME_USAGE = "Usage: cdx can-resume <name> [--json]"
+RESUME_USAGE = "Usage: cdx resume <name> [--conversation <id>] [--json]"
+CAN_RESUME_USAGE = "Usage: cdx can-resume <name> [--conversation <id>] [--json]"
+SESSIONS_USAGE = "Usage: cdx sessions [--all] --json"
 SELECT_USAGE = "Usage: cdx select --provider PROVIDER [--min-reasoning-effort minimal|low|medium|high|xhigh] [--min-power minimal|low|medium|high|xhigh] [--require-ready] [--refresh] --json"
 NEXT_USAGE = "Usage: cdx next [--json] [--refresh]"
 RUN_USAGE = "Usage: cdx run [session] (--cwd|--dir) 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 review|default|auto|full|workspace-write|read-only|danger-full-access] [--timeout-seconds N] [--label TEXT] [--max-parallel N] [--detach] [--failover] [--refresh] --json"
@@ -52,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,
@@ -61,7 +61,7 @@ RUN_PERMISSION_VALUES = PERMISSION_INPUT_VALUES
 RUN_PERMISSION_CANONICAL_VALUES = PERMISSION_VALUES
 RUN_PERMISSION_ALIASES = PERMISSION_ALIASES
 RUN_EFFORT_VALUES = REASONING_EFFORT_VALUES
-RUNS_USAGE = "Usage: cdx runs [--limit N] [--since 7d|today|DATE] --json"
+RUNS_USAGE = "Usage: cdx runs [--limit N] [--since 7d|today|DATE] [--running] --json"
 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"
@@ -80,6 +80,28 @@ ARG_CODE_OUT_OF_RANGE = "argument_value_out_of_range"
 ARG_CODE_UNKNOWN = "unknown_argument"
 
 
+def _pop_value_flag(args, flag, usage):
+    """Remove `flag VALUE` / `flag=VALUE` from args; return (value or None, rest)."""
+    value, rest, index = None, [], 0
+    while index < len(args):
+        arg = args[index]
+        name, sep, inline = arg.partition("=")
+        if name != flag:
+            rest.append(arg)
+            index += 1
+            continue
+        if sep:
+            candidate, index = inline, index + 1
+        elif index + 1 < len(args):
+            candidate, index = args[index + 1], index + 2
+        else:
+            raise CdxError(usage)
+        if value is not None or not candidate:
+            raise CdxError(usage)
+        value = candidate
+    return value, rest
+
+
 def _parse_json_flag(args):
     json_flag = "--json" in args
     cleaned = [arg for arg in args if arg != "--json"]
@@ -252,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")},
@@ -278,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:
@@ -301,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},
@@ -327,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]]
@@ -483,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`
@@ -671,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,
@@ -1033,8 +1046,13 @@ def _parse_runs_args(rest, now=None):
     parsed = _parse_flag_args(rest, {
         "--limit": {"key": "limit", "type": "str", "default": 20, "transform": _parse_positive_int},
         "--since": {"key": "since", "type": "str", "default": None},
+        "--running": {"key": "running", "type": "bool", "default": False},
         "--json": {"key": "json", "type": "bool", "default": False},
     }, RUNS_USAGE, max_positionals=0)
+    if parsed["running"] and parsed["since"] is not None:
+        # --since returns completed runs only, --running the ones not completed:
+        # together they can only ever answer "nothing".
+        raise CdxError("cdx runs: --running and --since are mutually exclusive.")
     since = None
     if parsed["since"] is not None:
         # Same cursor forms as `cdx history --since`, parsed by the same code:
@@ -1048,6 +1066,7 @@ def _parse_runs_args(rest, now=None):
         # a watchdog behind by more than `limit` completions would never see
         # the older ones at all.
         "limit_given": any(arg == "--limit" or arg.startswith("--limit=") for arg in rest),
+        "running": parsed["running"],
         "json": parsed["json"],
     }
 

package/src/cli_commands.py

@@ -265,6 +265,9 @@ from .commands.status import (
 from .commands.status import (
     handle_next as handle_next,
 )
+from .commands.status import (
+    handle_sessions as handle_sessions,
+)
 from .commands.status import (
     handle_stats as handle_stats,
 )

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,7 +8,8 @@ import shlex
 
 from .. import retro, shared_memory
 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 ..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,
     _json_failure,
@@ -30,6 +31,7 @@ from ..provider_runtime import (
     _ensure_session_authentication,
     _get_auth_home,
     _run_interactive_provider_command,
+    with_requested_conversation,
 )
 from ..run_command import PROMPT_STDIN, read_run_prompt
 from ..run_usage import estimate_cost
@@ -160,12 +162,14 @@ def _format_resume_capability(capability, use_color=False):
     )
 
 def handle_can_resume(rest, ctx):
+    conversation_id, rest = _pop_value_flag(rest, "--conversation", CAN_RESUME_USAGE)
     json_flag, args = _parse_json_flag(rest)
     if len(args) != 1:
         raise CdxError(CAN_RESUME_USAGE)
     session = ctx["service"]["get_session"](args[0])
     if not session:
         raise CdxError(f"Unknown session: {args[0]}")
+    requested = with_requested_conversation(session, conversation_id) if conversation_id else session
     if session.get("enabled", True) is False:
         capability = {
             "session": session["name"],
@@ -175,8 +179,19 @@ def handle_can_resume(rest, ctx):
             "reason": "session_disabled",
             "command_preview": [],
         }
+    elif requested is None:
+        capability = {
+            "session": session["name"],
+            "provider": session["provider"],
+            "resumable": False,
+            "strategy": "provider_conversation_id",
+            "identity": conversation_id,
+            "provenance": "requested",
+            "reason": "conversation_not_found",
+            "command_preview": [],
+        }
     else:
-        capability = _resume_capability_for_session(session, ctx)
+        capability = _resume_capability_for_session(requested, ctx)
     if json_flag:
         _write_json(ctx, {
             "schema_version": API_SCHEMA_VERSION,
@@ -188,13 +203,15 @@ def handle_can_resume(rest, ctx):
     return 0
 
 def handle_resume(rest, ctx):
+    conversation_id, rest = _pop_value_flag(rest, "--conversation", RESUME_USAGE)
     directory, rest, prompt = _parse_launch_args(rest)
     if prompt["prompt"] is not None or prompt["prompt_file"] is not None:
         raise CdxError("cdx resume: --prompt and --prompt-file are not supported when resuming.")
     json_flag, args = _parse_json_flag(rest)
     if len(args) != 1:
         raise CdxError(RESUME_USAGE)
-    return handle_launch(args[0], ctx, resume=True, force_json=json_flag, directory=directory)
+    return handle_launch(args[0], ctx, resume=True, force_json=json_flag, directory=directory,
+                         conversation_id=conversation_id)
 
 
 def _notification_provisioning_enabled(session, ctx, json_flag):
@@ -237,7 +254,8 @@ def _link_shared_memory(session, ctx, cwd, json_flag):
     ctx["out"](f"{_warn(message, ctx['use_color'])} {detail}\n")
 
 
-def handle_launch(command, ctx, initial_prompt=None, resume=False, force_json=None, directory=None):
+def handle_launch(command, ctx, initial_prompt=None, resume=False, force_json=None, directory=None,
+                  conversation_id=None):
     json_flag = "--json" in ctx.get("raw_args", ctx["options"].get("raw_args", []))
     if force_json is not None:
         json_flag = force_json
@@ -250,6 +268,8 @@ def handle_launch(command, ctx, initial_prompt=None, resume=False, force_json=No
         raise CdxError(f"Unknown session: {command}")
     if session.get("enabled", True) is False:
         raise CdxError(f"Session is disabled: {command}")
+    if conversation_id and with_requested_conversation(session, conversation_id) is None:
+        raise CdxError(f"Conversation {conversation_id} not found in session {command}.", code="conversation_not_found")
     capability = _resume_capability_for_session(session, ctx) if resume else None
     if capability and not capability["resumable"]:
         raise CdxError(
@@ -257,6 +277,8 @@ def handle_launch(command, ctx, initial_prompt=None, resume=False, force_json=No
         )
     cwd = _launch_directory(session, ctx, directory, json_flag)
     session = ctx["service"]["launch_session"](command, resume=resume)
+    if conversation_id:
+        session = with_requested_conversation(session, conversation_id)
     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")
@@ -280,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

@@ -43,7 +43,7 @@ from ..provider_runtime import (
 )
 from ..run_command import read_run_prompt, run_cdx_error_code, run_launch_payload, run_result_payload
 from ..run_failover import MAX_FAILOVER_TRANSITIONS, failover_reason
-from ..run_registry import RunRegistry, build_code_review_report
+from ..run_registry import RunRegistry, build_code_review_report, final_message
 from ..run_usage import extract_run_observation
 from ..session_ranking import FACTOR_DESCRIPTIONS, rank_sessions, selection_policy
 from ..status_view import _now_timestamp, _priority_reset_timestamp
@@ -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
 
@@ -415,7 +419,7 @@ def handle_runs(rest, ctx):
         raise CdxError(RUNS_USAGE)
     since = parsed.get("since")
     _reconcile_background_runs(ctx)
-    runs = _run_registry(ctx).list(limit=parsed["limit"], since=since)
+    runs = _run_registry(ctx).list(limit=parsed["limit"], since=since, running=parsed.get("running", False))
     warnings = []
     if since is not None and parsed.get("limit_given"):
         warnings.append({
@@ -503,6 +507,7 @@ def handle_run_report(rest, ctx):
     _write_json(ctx, _json_success("run-report", "Run report loaded.", report={
         "run": run,
         "final_payload": run.get("final_payload"),
+        "final_message": final_message(run),
         "task_report": run.get("task_report"),
         "artifacts": run.get("artifacts") or {},
         "usage": run.get("usage"),
@@ -636,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/commands/status.py

@@ -12,6 +12,7 @@ from datetime import datetime
 from ..claude_refresh import _refresh_claude_sessions
 from ..cli_args import (
     LAST_USAGE,
+    SESSIONS_USAGE,
     STATUS_USAGE,
     _filter_history_period,
     _has_history_period,
@@ -59,6 +60,7 @@ from ..run_usage import (
     token_prices,
     weighted_usage,
 )
+from ..session_status import session_paths
 from ..status_view import _format_status_detail, _format_status_rows, format_priority_instruction, recommend_priority_rows
 
 
@@ -926,3 +928,39 @@ def _write_refresh_warnings(refresh_errors, ctx, stream="out", rows=None):
     rows_by_name = _rows_by_session(rows)
     for item in refresh_errors:
         write(f"{_warn(_format_refresh_warning(item, rows_by_name), ctx['use_color'])}\n")
+
+
+def handle_sessions(rest, ctx):
+    """Interactive sessions cdx launched that are still running, or every account.
+
+    Read from the runtime cdx records at launch, so a provider started outside
+    cdx is not listed. A runtime whose process has died is reported stale and
+    dropped by the same check `cdx status` uses for `active`. `--all` adds the
+    idle enabled accounts, so a caller can resolve any account's directories.
+    """
+    json_flag, args = _parse_json_flag(rest)
+    include_all = "--all" in args
+    args = [arg for arg in args if arg != "--all"]
+    if not json_flag or args:
+        raise CdxError(SESSIONS_USAGE)
+    service = ctx["service"]
+    rows = []
+    for session in service["list_sessions"]():
+        if session.get("enabled", True) is False:
+            continue
+        runtime = service["active_session_runtime"](session["name"]) or {}
+        if not runtime and not include_all:
+            continue
+        rows.append({
+            "session": session["name"],
+            "provider": session["provider"],
+            "active": bool(runtime),
+            "pid": runtime.get("pid"),
+            "cwd": runtime.get("cwd"),
+            "started_at": runtime.get("startedAt"),
+            "runtime_id": runtime.get("runId"),
+            "conversation_id": (session.get("conversation") or {}).get("id"),
+            **session_paths(session),
+        })
+    _write_json(ctx, _json_success("sessions", "Sessions loaded.", sessions=rows))
+    return 0

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:
@@ -820,6 +821,18 @@ def _conversation_is_resumable(session, provider, conversation_id):
         return False
 
 
+def with_requested_conversation(session, conversation_id):
+    """The session as if `conversation_id` were the one it last opened.
+
+    Returns None when that conversation does not exist in this session's
+    profile: an explicitly named resume must fail, not quietly fall back to
+    --last/--continue and open a different conversation.
+    """
+    if not _conversation_is_resumable(session, session.get("provider"), conversation_id):
+        return None
+    return {**session, "conversation": {"id": conversation_id, "provenance": "requested"}}
+
+
 def _redacted_resume_command_preview(session, cwd=None):
     capability = get_resume_capability(session, cwd=cwd)
     return capability.get("command_preview")

package/src/run_registry.py

@@ -7,7 +7,7 @@ from datetime import datetime, timezone
 
 from .errors import CdxError
 from .fs_utils import atomic_write
-from .run_usage import coerce_usage
+from .run_usage import _parse_json_records, coerce_usage
 from .session_helpers import _process_is_running
 
 
@@ -367,7 +367,7 @@ class RunRegistry:
             return run
         return None
 
-    def list(self, limit=20, since=None):
+    def list(self, limit=20, since=None, running=False):
         """Recent runs, newest first.
 
         `since` selects every run that *completed* strictly after that moment
@@ -384,6 +384,10 @@ class RunRegistry:
             if changed:
                 _write_registry(self.path, data)
         runs = data["runs"]
+        if running:
+            # Every in-flight run, uncapped: a caller counting live runs against
+            # a cap must not be handed a truncated count.
+            return [run for run in runs if run.get("status") == "running"]
         if since is not None:
             return [run for run in runs if _completed_after(run, since)]
         return runs[: max(0, int(limit or 20))]
@@ -410,6 +414,51 @@ def read_text_file(path, limit=120000):
         return ""
 
 
+def _record_final_message(record):
+    """The final assistant text one provider record carries, or None."""
+    if not isinstance(record, dict):
+        return None
+    # Claude: `--output-format json` ends with a `result` envelope.
+    if record.get("type") == "result" and isinstance(record.get("result"), str):
+        return record["result"]
+    # Codex `exec --json`: an `item.completed` event wrapping an agent_message.
+    item = record.get("item")
+    if isinstance(item, dict) and item.get("type") == "agent_message" and isinstance(item.get("text"), str):
+        return item["text"]
+    # Older Codex builds wrapped it as {"msg": {"type": "agent_message", "message": ...}}.
+    msg = record.get("msg")
+    if isinstance(msg, dict) and msg.get("type") == "agent_message" and isinstance(msg.get("message"), str):
+        return msg["message"]
+    return None
+
+
+def final_message(run):
+    """The run's last assistant message, read the same way for every provider.
+
+    A `--bg` run records it from the transcript as `final_payload.result`; any
+    other run left it in its stdout, in the provider's own event format. None
+    when neither holds one (a plain-text provider, a run that died early).
+    """
+    result = (run.get("final_payload") or {}).get("result")
+    if isinstance(result, str) and result.strip():
+        return result
+    stdout_path = (run.get("artifacts") or {}).get("stdout_path")
+    if not stdout_path:
+        return None
+    try:
+        with open(stdout_path, encoding="utf-8", errors="replace") as handle:
+            text = handle.read()
+    except OSError:
+        return None
+    if not text.strip():
+        return None
+    for record in reversed(_parse_json_records(text)):
+        message = _record_final_message(record)
+        if message is not None:
+            return message
+    return None
+
+
 def build_code_review_report(run_id, final_payload):
     stdout = read_text_file(final_payload.get("stdout_path") if final_payload else None)
     parsed = None

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]

package/src/session_status.py

@@ -338,6 +338,25 @@ def _fetch_codex_status(codex_status_fetcher, custom_codex_status_fetcher, defau
     timeout = timeout_seconds or default_status_timeout_seconds
     return codex_status_fetcher(session, timeout=timeout)
 
+def session_paths(session):
+    """Where a session's files live, so a caller never rebuilds cdx's layout.
+
+    `profile_dir` is the session's own directory and `transcripts_dir` the
+    provider's conversation store inside it (None for a provider cdx does not
+    read transcripts from). The credential home itself is deliberately not
+    named, the same rule `cdx status` rows follow.
+    """
+    auth_home = session.get("authHome")
+    transcripts = {
+        PROVIDER_CLAUDE: (".claude", "projects"),
+        PROVIDER_CODEX: ("sessions",),
+    }.get(session.get("provider"))
+    return {
+        "profile_dir": session.get("sessionRoot") or auth_home,
+        "transcripts_dir": os.path.join(auth_home, *transcripts) if auth_home and transcripts else None,
+    }
+
+
 def _status_row_from_session(store, s):
     status = s.get("lastStatus")
     enabled = s.get("enabled", True) is not False