cdx-manager 0.22.0 → 0.23.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.23.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.
 

package/VERSION

@@ -1 +1 @@
-0.22.0
+0.23.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/checksums/release-archives.json

@@ -551,6 +551,17 @@
         "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"
+      }
     }
   }
 }

package/docs/cli.md

@@ -28,8 +28,9 @@
 | `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 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` |
@@ -53,10 +54,10 @@
 | `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-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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "cdx-manager",
-  "version": "0.22.0",
+  "version": "0.23.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.23.0"
 description = "Terminal session manager for Codex and Claude accounts."
 readme = "README.md"
 requires-python = ">=3.9"

package/src/cli.py

@@ -50,6 +50,7 @@ from .cli_commands import (
     handle_runs,
     handle_schema,
     handle_select,
+    handle_sessions,
     handle_set,
     handle_stats,
     handle_status,
@@ -187,6 +188,7 @@ _COMMAND_HANDLERS = {
     "runs": handle_runs,
     "schema": handle_schema,
     "select": handle_select,
+    "sessions": handle_sessions,
     "set": handle_set,
     "stats": handle_stats,
     "status": handle_status,
@@ -241,9 +243,10 @@ def _print_help(use_color=False):
         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 +260,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

@@ -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"
@@ -61,7 +62,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 +81,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"]
@@ -1033,8 +1056,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 +1076,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/commands/launch.py

@@ -8,7 +8,7 @@ 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 ..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 +30,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 +161,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 +178,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 +202,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 +253,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 +267,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 +276,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")

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
@@ -415,7 +415,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 +503,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"),

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

@@ -820,6 +820,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_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