cdx-manager 0.24.8 → 0.24.9

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.24.8-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.9-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.
 
@@ -42,6 +42,23 @@ cdx work
 
 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`.
 
+## Cache efficiency and fix rounds
+
+`cdx history --json` records uncached input, cache reads, cache writes, output tokens, and `usage.cache_hit_ratio` beside the existing token totals. The ratio is cache reads divided by all input tokens, excluding output. Missing provider splits stay `null`, and text views show `cache n/d` instead of claiming a zero hit rate.
+
+`cdx stats --json` adds `cache_usage` sums and an input-weighted `cache_hit_ratio` to each session, project (`--by project`), model (`--by model`), and total. `cache_usage` preserves unknown sums as `null`; existing numeric aggregate fields keep their previous behavior. Ratios include only runs with measured input and cache reads. Coverage is explicit in `measured_runs` and `measured_input_tokens`. `run_types.cold` and `run_types.continued` expose counts, sums, and ratios for comparison. Text views show values such as `cache 72 %` next to tokens.
+
+Reuse a completed run's provider conversation for another fix round:
+
+```bash
+cdx run work --cwd /path/to/repo --prompt "Implement the change" --reasoning-effort high --json
+cdx run --continue-run RUN_ID --cwd /path/to/repo --prompt "Fix the remaining test failure" --json
+```
+
+`--continue-run` resumes the exact Claude session or Codex thread and pins the previous run's recorded model and effort, even if the profile settings changed. The profile is inferred from the parent; an explicit session or provider must match. An explicit model or effort must also match. Runs and history record `parent_run_id` and `conversation_id`. Detached continuations use the cdx child supervisor with the same pins. Codex continuation usage is measured between exact transcript snapshots before and after the run, since exec resume can report conversation totals. If either boundary is unavailable, per-run usage stays unknown with `usage_attribution: "continuation_usage_unavailable"` in history instead of counting earlier turns again.
+
+Conservative assumption: a continuation requires a finished Claude or Codex run, a locally available provider transcript, and recorded model and effort settings. Missing runs, profiles, expired sessions, and unavailable settings produce a clear error; the caller can retry without `--continue-run` for a cold run. `--failover` and `--isolate-workspace` cannot be combined with continuation. Capacity recovery and provider model fallback are disabled for continuations so they cannot silently switch model or account. Provider cache retention remains provider-controlled, so resuming does not guarantee a cache hit.
+
 ## Codex model capacity recovery
 
 `cdx run` (including `--detach`) automatically recovers from Codex's "Selected model is at capacity" failure. It retries the same prompt, profile, and model after 1 and 2 seconds, then tries the profile's `fallback_model` list in configured order, removing duplicates. Configure alternatives with `cdx set work --fallback-model MODEL_A,MODEL_B`.

package/VERSION

@@ -1 +1 @@
-0.24.8
+0.24.9

package/changelogs/CHANGELOGS_0_24_8.md

@@ -10,6 +10,14 @@ This patch improves recovery from Codex model capacity failures. (#67)
 - Exclude disabled, logged-out, `never`, and `ask-first` profiles from automatic fallback. Limit recovery to three attempts per model and four profile switches, reporting `capacity_recovery_exhausted` when no eligible alternative remains or the budget is exhausted. (#67)
 - Log recovery actions to stderr and structured run data, preserve failed attempt output, and report the effective model without changing profile settings. (#67)
 
+## Token efficiency
+
+- Record per-run cache hit ratios beside the existing cache read, cache write, uncached input, output, and total token fields. Preserve missing provider splits as `null` in headless, interactive, and background usage readers.
+- Add nullable `cache_usage` sums, input-weighted ratios, measurement coverage, and cold versus continued comparisons to stats by session, project, and model. Display `cache 72 %` or `cache n/d` beside tokens without changing existing JSON fields.
+- Add `cdx run --continue-run RUN_ID` for native Claude and Codex conversation resume with pinned model and reasoning effort, including detached runs. Persist parent links and exact conversation identities. Refuse missing, mismatched, expired, or unpinnable parents; prevent model/account fallback during a continuation.
+- Measure Codex continuation usage from exact transcript boundaries so cumulative conversation totals are not billed again. Parse cache write counts when Codex reports them.
+- Add provider parsing, JSON compatibility, aggregation, continuation validation, settings pinning, refusal, and parent-link regression tests.
+
 ## Maintenance
 
 - Record tray companion checksums for v0.24.7. (`16938c0d22de4589f5b4757fd7ff55e848127e7d`)

package/changelogs/CHANGELOGS_0_24_9.md

@@ -0,0 +1,18 @@
+# CDX Manager 0.24.9
+
+Release date: 2026-10-30
+
+This patch tracks cache efficiency and resumes runs with pinned settings. (#69)
+
+## Cache efficiency and run continuation
+
+- Record per-run cache hit ratios alongside cache read, cache write, uncached input, output, and total token counts. Preserve unknown provider splits as `null`. (#69)
+- Add nullable `cache_usage` summaries, input-weighted cache hit ratios, measurement coverage, and cold versus continued run comparisons to stats by session, project, and model. Show cache efficiency beside token counts in history and stats. (#69)
+- Add `cdx run --continue-run RUN_ID` to resume the exact Claude or Codex conversation from a finished run with its recorded profile, model, and reasoning effort, including detached runs. Preserve parent run links and provider conversation identities. (#69)
+- Refuse unavailable parents, missing transcripts, mismatched profiles, and incompatible settings. Keep continuation settings pinned by disabling automatic capacity recovery and model fallback, and rejecting `--failover` and `--isolate-workspace`. (#69)
+- Attribute Codex continuation usage to exact transcript boundaries so earlier turns are not counted again. Leave per-run usage unknown when those boundaries are unavailable, and parse cache write counts when reported. (#69)
+
+## Maintenance
+
+- Record tray companion checksums for v0.24.8. (`2f1bb93db481ff6f06d8c61435a228ae9de9c4be`)
+- Record release archive checksums for v0.24.8. (`7ff1b1cc0b11016adc5c1a30135f1553af3a53d7`)

package/checksums/release-archives.json

@@ -661,6 +661,17 @@
         "x86_64-pc-windows-msvc": "41df35daa664802b87c052d6a9f634b240eb4e4a915868f1dd629b6734eab76a",
         "x86_64-unknown-linux-musl": "2492e137e5c883fa16f502843a867e0325744dfc66d7d38be2c00eb362425af6"
       }
+    },
+    "v0.24.8": {
+      "github_tarball_sha256": "4e34a7c7411cca9bfe568b07dc997c0d992d6c97806dbf091558cf2a826d6c1c",
+      "github_zip_sha256": "ec3f52aba6d645e1ab8990d763b4b761703e1e455f8bf40b58d6a47a01374d66",
+      "tray_assets": {
+        "aarch64-apple-darwin": "87a3abf4bf9f024ed1dfad74e6b2fe0734b9ae5811e4f6d93da7bdcab02fad66",
+        "aarch64-unknown-linux-musl": "32e7481d86be156e6c5e94d25473ff595e2596686c81ebdeff4cb719b993c7d2",
+        "x86_64-apple-darwin": "644a0a60b7d740c0853e426f69021cdc323b01438e0bcdf5f2792e8b9e3005c3",
+        "x86_64-pc-windows-msvc": "6df3f25ab6a9aa02a45aa6f90f95c3484553b248175394af9ecfd12668479281",
+        "x86_64-unknown-linux-musl": "ea867d352a18db59e882d6abbdbafa61b54fbec7fafa66746852696cf18cd6c5"
+      }
     }
   }
 }

package/docs/cli.md

@@ -56,7 +56,7 @@
 | `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 (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 [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] [--continue-run RUN_ID] [--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 |
@@ -241,6 +241,10 @@ The result includes `launcher: "cdx"`, `run_id`, selected `session`, `provider`,
 
 Known headless and completed interactive token usage is persisted in launch history and can be aggregated later. Interactive records are best-effort local data: Codex reads its latest cumulative rollout snapshot, Claude reads its assistant usage records, and Ollama — which writes no transcript of its own — is launched with `--verbose` so its per-response token counts land in the terminal capture cdx already takes. Antigravity reports no usage: its history is schema-less binary protobuf and its logs carry no usage line, so those sessions show no tokens by nature rather than by omission.
 
+`--continue-run RUN_ID` resumes the exact provider conversation from a finished Claude or Codex run, inferring its profile and pinning its recorded model and effort. Existing targets and settings may be supplied only if they match. The parent transcript must still exist. `parent_run_id` links the new run to its parent in run results, the registry, and history; `conversation_id` identifies the provider conversation. Detached continuations preserve these settings through the cdx supervisor. Codex continuation usage is measured between exact transcript snapshots before and after the run, since exec resume can report conversation totals. If either boundary is unavailable, per-run usage stays unknown with `usage_attribution: "continuation_usage_unavailable"` in history instead of counting earlier turns again. Continuation does not use automatic capacity recovery or model fallback, and cannot be combined with `--failover` or `--isolate-workspace`.
+
+Continuation errors are `continue_run_not_found` (unknown parent), `continue_run_mismatch` (another or missing profile/provider), `continue_run_unavailable` (unfinished or unsupported run, expired transcript, or unavailable settings), and `continue_run_settings_mismatch` (changed model/effort or incompatible flags). Callers may start a normal run after a refusal by omitting `--continue-run`.
+
 Every usage record, whichever path produced it, uses one set of definitions:
 
 | Field | Meaning |
@@ -251,11 +255,14 @@ Every usage record, whichever path produced it, uses one set of definitions:
 | `cache_read_tokens` | Tokens served from it. Kept apart from cache creation because the two cost roughly 1.25x and 0.1x of uncached input, a difference no summed figure can recover. |
 | `cached_input_tokens` | `cache_creation_tokens + cache_read_tokens`, derived. The single CACHE column in `cdx stats` shows this. |
 | `output_tokens` | Generated tokens. |
+| `cache_hit_ratio` | Cache reads divided by uncached input plus cache writes plus cache reads, excluding output. A fraction from 0 to 1; `null` without a reported read split or with zero input. When Codex omits writes, its reported total input is uncached input plus reads. |
 | `reasoning_tokens` | Reasoning the provider counts separately. Codex reports one; Claude does not, because it bills thinking as output — those tokens are already inside `output_tokens`, so an empty REASON column for Claude is correct rather than missing. |
 | `total_tokens` | `input + cache_creation + cache_read + output`. Cache is typically the bulk of real consumption, so a total that left it out would not be slightly low — it would be a different quantity. |
 
 Cached input is counted once: it is excluded from `input_tokens` and reported in the cache fields, never in both. `null` means the provider did not report the figure, which is not the same as zero.
 
+History and stats text show `cache 72 %` beside tokens, or `cache n/d` for unknown splits. Stats JSON adds `cache_usage` with nullable sums for `input_tokens`, `cache_creation_tokens`, `cache_read_tokens`, and `output_tokens`. Existing numeric aggregate fields are unchanged. `cache_hit_ratio` is computed from summed reads and input across measured runs, never by averaging percentages. `measured_runs`, `measured_input_tokens`, and `measured_cache_read_tokens` describe ratio coverage, excluding missing splits and zero-input runs. Each session, project, model, and total includes `run_types.cold` and `run_types.continued`, each with `runs` and the same cache summary fields. A missing `parent_run_id` counts as cold for historical compatibility.
+
 `cdx stats` also shows a **`COST~`** column and ranks sessions by it. It weights each token class by what it costs relative to one uncached input token — cache read at the recorded model's ratio (0.1x by default), cache write 1.25x (2x for one-hour writes), and output at the recorded model's output/input ratio — and reports the result in uncached-input-equivalent tokens. These are ratios rather than prices. It is **not** a currency amount, and it is not comparable across providers whose own prices differ. Writes reported as one-hour are weighted 2x; a record without that split keeps the five-minute 1.25x rate.
 
 Ranking on the raw total would put a session that mostly replayed a cache above one that spent far more on generation, because cache reads are typically the overwhelming majority of tokens consumed while costing a fiftieth of an output token.

package/package.json

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

package/src/cli.py

@@ -245,7 +245,7 @@ def _print_help(use_color=False):
         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 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] [--continue-run RUN_ID] [--detach] [--failover] [--refresh] --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)}",

package/src/cli_args.py

@@ -47,7 +47,7 @@ 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] [--network-access] [--isolate-workspace] [--timeout-seconds N] [--label TEXT] [--max-parallel N] [--detach] [--failover] [--refresh] --json"
+RUN_USAGE = "Usage: cdx run [session] (--cwd|--dir) PATH (--prompt-file PATH|--prompt TEXT|--prompt-file -) [--provider PROVIDER] [--model MODEL] [--kind assistant|code-review|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] [--network-access] [--isolate-workspace] [--timeout-seconds N] [--label TEXT] [--max-parallel N] [--continue-run RUN_ID] [--detach] [--failover] [--refresh] --json"
 RUN_JSON_REQUIRED = "cdx run: --json is required."
 RUN_TARGET_REQUIRED = "cdx run: specify a session name or --provider PROVIDER."
 RUN_SESSION_PROVIDER_CONFLICT = "cdx run: cannot specify both a session name and --provider."
@@ -544,6 +544,10 @@ def cdx_schema():
                 "failover_exhausted",
                 "failover_limit_reached",
                 "capacity_recovery_exhausted",
+                "continue_run_not_found",
+                "continue_run_mismatch",
+                "continue_run_unavailable",
+                "continue_run_settings_mismatch",
                 "invalid_request",
                 "cdx_error",
             ],
@@ -661,6 +665,7 @@ def _parse_run_args(args):
         "--prompt": {"key": "prompt", "type": "str", "default": None},
         "--provider": {"key": "provider", "type": "str", "default": None, "transform": _parse_run_provider},
         "--model": {"key": "model", "type": "str", "default": None},
+        "--continue-run": {"key": "continue_run", "type": "str", "default": None},
         "--kind": {"key": "kind", "type": "str", "default": "assistant"},
         "--reasoning-effort": {"key": "reasoning_effort", "type": "str", "default": None},
         "--power": {"key": "power", "type": "str", "default": None},
@@ -684,7 +689,7 @@ def _parse_run_args(args):
             code=ARG_CODE_MUTUALLY_EXCLUSIVE,
             arguments=["session", "--provider"],
         )
-    if not name and not parsed["provider"]:
+    if not name and not parsed["provider"] and not parsed["continue_run"]:
         raise CdxArgumentError(RUN_TARGET_REQUIRED, code=ARG_CODE_MISSING, arguments=["session", "--provider"])
     if not parsed["cwd"]:
         raise CdxArgumentError(RUN_CWD_REQUIRED, code=ARG_CODE_MISSING, arguments=["--cwd"])
@@ -708,6 +713,9 @@ def _parse_run_args(args):
             arguments=["--kind"],
             allowed=RUN_KIND_VALUES,
         )
+    if parsed["continue_run"] is not None and not parsed["continue_run"].strip():
+        raise CdxArgumentError("cdx run: --continue-run requires a nonempty run id.",
+                               code=ARG_CODE_INVALID_VALUE, arguments=["--continue-run"])
     effort = _parse_run_effort(parsed["reasoning_effort"], parsed["power"])
     return {
         "name": name,
@@ -715,6 +723,7 @@ def _parse_run_args(args):
         "cwd": parsed["cwd"],
         "prompt_file": parsed["prompt_file"],
         "prompt": parsed["prompt"],
+        "continue_run": parsed["continue_run"],
         "kind": parsed["kind"],
         "model": parsed["model"],
         "permission": parsed["permission"],

package/src/commands/launch.py

@@ -34,7 +34,7 @@ from ..provider_runtime import (
     with_requested_conversation,
 )
 from ..run_command import PROMPT_STDIN, read_run_prompt
-from ..run_usage import estimate_cost
+from ..run_usage import estimate_cost, format_cache_ratio
 
 LAUNCH_USAGE = "Usage: cdx <name> [--dir PATH] [--prompt TEXT|--prompt-file PATH|--task TEXT [--end-state TEXT]] [--resume] [--on-busy fail|ask] [--json]"
 
@@ -425,9 +425,9 @@ def _goodbye_line(session, run_info, use_color):
     if cost is not None:
         parts.append(_format_usd(cost))
     elif isinstance(usage, dict):
-        total_tokens = sum(v for v in usage.values() if isinstance(v, (int, float)))
+        total_tokens = usage.get("total_tokens")
         if total_tokens:
-            parts.append(f"{_format_token_count(total_tokens)} tokens")
+            parts.append(f"{_format_token_count(total_tokens)} tokens {format_cache_ratio(usage.get('cache_hit_ratio'))}")
     return _dim(" · ".join(parts), use_color)
 
 
@@ -482,7 +482,7 @@ def _attach_interactive_usage(session, run_info, history=None, baseline=None, un
     else:
         previous = _previous_cumulative(history, provider_transcript)
     if previous is not None:
-        delta = usage_delta(cumulative, previous)
+        delta = usage_delta(cumulative, previous, provider=session.get("provider"))
         if delta is not None:
             run_info["usage"] = delta
         # A None delta means the transcript shrank, rotated, or was replaced.

package/src/commands/runs.py

@@ -23,7 +23,9 @@ from ..cli_args import (
     cdx_schema,
 )
 from ..cli_helpers import API_SCHEMA_VERSION, _json_failure, _json_success, _write_json
+from ..config import split_extra_args
 from ..errors import CdxError
+from ..interactive_usage import MEASURED_KEYS, extract_interactive_usage, usage_delta
 from ..provider_background import (
     BACKGROUND_PATH_CDX,
     BACKGROUND_PATH_PROVIDER,
@@ -41,9 +43,11 @@ from ..provider_runtime import (
     _build_launch_spec,
     _ensure_session_authentication,
     _headless_artifact_paths,
+    _launch_power,
     _restore_signal_handlers,
     _route_termination_to_interrupt,
     _run_headless_provider_command,
+    with_requested_conversation,
 )
 from ..run_command import read_run_prompt, run_cdx_error_code, run_launch_payload, run_result_payload
 from ..run_failover import (
@@ -54,7 +58,7 @@ from ..run_failover import (
     looks_model_at_capacity,
 )
 from ..run_registry import RunRegistry, build_code_review_report, final_message
-from ..run_usage import extract_run_observation
+from ..run_usage import empty_usage, extract_run_conversation_id, extract_run_observation
 from ..session_ranking import FACTOR_DESCRIPTIONS, rank_sessions, selection_policy
 from ..status_view import _now_timestamp, _priority_reset_timestamp
 
@@ -200,6 +204,7 @@ def _detached_child_argv(parsed, prompt_path, session_name, cwd):
     # from the package root, so a relative "--cwd ." would resolve there.
     argv = ["run", session_name, "--cwd", cwd, "--prompt-file", prompt_path]
     for flag, key in (
+        ("--continue-run", "continue_run"),
         ("--model", "model"),
         ("--kind", "kind"),
         ("--permission", "permission"),
@@ -537,6 +542,77 @@ def _env_max_runs(ctx):
     return limit if limit > 0 else None
 
 
+def _observe_headless_usage(session, run_info, baseline=None):
+    usage, model = extract_run_observation(session.get("provider"), run_info.get("stdout_path"), session.get("authHome"))
+    observation = {"usage": usage, "usage_model": model}
+    if baseline is not None:
+        cumulative, path, match, transcript_model = extract_interactive_usage(
+            session["provider"], session.get("authHome"), conversation_id=(session.get("conversation") or {}).get("id"))
+        before, before_path, _before_match, _before_model = baseline
+        comparable = (cumulative and before and path == before_path
+                      and all((cumulative.get(key) is None) == (before.get(key) is None) for key in MEASURED_KEYS))
+        # A newly reported split includes unknown pre-launch usage; losing a
+        # split also prevents a comparable measurement across the boundary.
+        delta = usage_delta(cumulative, before, provider=session.get("provider")) if comparable else None
+        # Exec resume can emit conversation totals. Only exact launch boundaries
+        # establish this run's share; stdout cannot replace a missing boundary.
+        observation.update(usage=delta if delta is not None else empty_usage(), usage_cumulative=cumulative,
+                           usage_attribution="launch_boundary" if delta is not None else "continuation_usage_unavailable",
+                           provider_transcript_path=path, provider_transcript_match=match,
+                           usage_model=model or transcript_model)
+    return observation
+
+
+def _continue_run_session(parsed, ctx):
+    """Resolve only the parent's profile and exact persisted conversation."""
+    previous = _run_registry(ctx).get(parsed["continue_run"])
+    if not previous:
+        raise CdxError(f"Cannot continue unknown run: {parsed['continue_run']}. Start a normal run instead.",
+                       code="continue_run_not_found")
+    name, provider = previous.get("session"), previous.get("provider")
+    if (parsed.get("name") and parsed["name"] != name) or (parsed.get("provider") and parsed["provider"] != provider):
+        raise CdxError("Cannot continue a run from another profile or provider. Start a normal run instead.",
+                       code="continue_run_mismatch")
+    session = ctx["service"]["get_session"](name) if name else None
+    if not session or session.get("provider") != provider:
+        raise CdxError("The previous run's profile or provider is no longer available. Start a normal run instead.",
+                       code="continue_run_mismatch")
+    if provider not in ("claude", "codex") or previous.get("status") not in ("succeeded", "failed", "timed_out", "cancelled"):
+        raise CdxError("Only a finished Claude or Codex run can be continued. Start a normal run instead.",
+                       code="continue_run_unavailable")
+    conversation = previous.get("conversation_id")
+    resumed = with_requested_conversation(session, conversation)
+    if not resumed:
+        raise CdxError("The previous run's provider session expired or its transcript is missing. Start a normal run instead.",
+                       code="continue_run_unavailable")
+    model = previous.get("usage_model") or previous.get("model")
+    effort = previous.get("reasoning_effort")
+    if not isinstance(model, str) or not model or model.startswith("<") or not effort or not previous.get("launch"):
+        raise CdxError("The previous run's model and effort cannot be pinned. Start a normal run instead.",
+                       code="continue_run_unavailable")
+    if ((parsed.get("model") and parsed["model"] != model)
+            or (parsed.get("reasoning_effort") and parsed["reasoning_effort"] != effort)):
+        raise CdxError("--continue-run requires the previous run's model and reasoning effort.",
+                       code="continue_run_settings_mismatch")
+    if parsed.get("failover") or parsed.get("isolate_workspace"):
+        raise CdxError("--continue-run cannot be combined with --failover or --isolate-workspace.",
+                       code="continue_run_settings_mismatch")
+    if provider == "claude":
+        # Passthrough options are appended last and can override the pinned settings.
+        pinned_options = {"--model", "--effort", "--fallback-model", "--resume", "--continue",
+                          "--session-id", "--fork-session", "--resume-session-at", "--from-pr",
+                          "--settings", "--agent", "--agents"}
+        for arg in split_extra_args((session.get("launch") or {}).get("extra_args")) or []:
+            if arg.split("=", 1)[0] in pinned_options or arg.startswith(("-r", "-c")):
+                raise CdxError("--continue-run cannot use Claude extra_args that override model, effort, or conversation.",
+                               code="continue_run_settings_mismatch")
+    parsed.update(name=name, model=model, reasoning_effort=effort, power=effort)
+    launch = {**(session.get("launch") or {}), "model": model, "reasoning_effort": effort, "power": effort}
+    # A provider fallback would break the model pin even though cdx stayed on this profile.
+    launch.pop("fallback_model", None)
+    return {**resumed, "launch": launch, "continue_run": parsed["continue_run"]}
+
+
 def handle_run(rest, ctx):
     registry = None
     run_id = None
@@ -548,8 +624,11 @@ def handle_run(rest, ctx):
     detached_run_id = os.environ.pop(DETACHED_RUN_ID_ENV, None) or None
     try:
         parsed = _parse_run_args(rest)
-        session = None
-        if parsed["name"]:
+        session = _continue_run_session(parsed, ctx) if parsed.get("continue_run") else None
+        if session:
+            if session.get("enabled", True) is False:
+                raise CdxError(f"Session is disabled: {session['name']}", code="session_disabled")
+        elif parsed["name"]:
             session = ctx["service"]["get_session"](parsed["name"])
             if not session:
                 raise CdxError(f"Unknown session: {parsed['name']}")
@@ -604,7 +683,8 @@ def handle_run(rest, ctx):
         # records its own afterwards, from the rollout. Without this a headless
         # Claude run left the session with no identity and `cdx resume` fell
         # back to recency for Claude while working by id for Codex.
-        session = ctx["service"]["begin_conversation"](session["name"])
+        if not parsed.get("continue_run"):
+            session = ctx["service"]["begin_conversation"](session["name"])
         run_session = {
             **session,
             "launch": {
@@ -646,6 +726,10 @@ def handle_run(rest, ctx):
             },
             label=parsed.get("label"),
             max_parallel=max_parallel,
+            parent_run_id=parsed.get("continue_run"),
+            conversation_id=(run_session.get("conversation") or {}).get("id") if run_session["provider"] == "claude" or parsed.get("continue_run") else None,
+            launch=run_session.get("launch"),
+            reasoning_effort=_launch_power(run_session),
         )
         if parsed.get("detach"):
             # Delegate where the installed CLI can both start a background
@@ -654,7 +738,7 @@ def handle_run(rest, ctx):
             launch = None
             # 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("isolate_workspace") and not parsed.get("network_access") and not parsed.get("failover") and supports_native_background(
+            if not parsed.get("continue_run") and not parsed.get("isolate_workspace") and not parsed.get("network_access") and not parsed.get("failover") and supports_native_background(
                 run_session.get("provider"),
                 env=ctx.get("env"),
                 spawn_sync=ctx.get("spawn_text"),
@@ -680,6 +764,7 @@ def handle_run(rest, ctx):
                 cwd=cwd,
                 pid=launch.get("pid"),
                 launch_log_path=launch.get("launch_log_path"),
+                conversation_id=launch.get("provider_session_id"),
                 selection_row=selection_row,
             ))
             return 0
@@ -693,6 +778,10 @@ def handle_run(rest, ctx):
         capacity_retries = 0
         while True:
             attempt += 1
+            baseline = extract_interactive_usage(
+                run_session["provider"], run_session.get("authHome"),
+                conversation_id=(run_session.get("conversation") or {}).get("id"),
+            ) if parsed.get("continue_run") and run_session["provider"] == "codex" else None
             run_info = _run_headless_provider_command(
                 run_session,
                 cwd=cwd,
@@ -702,11 +791,13 @@ def handle_run(rest, ctx):
                 spawn=ctx.get("spawn_headless") or ctx.get("spawn"),
                 run_id=run_id,
             )
-            usage, usage_model = extract_run_observation(
-                run_session.get("provider"), run_info.get("stdout_path"),
-                run_session.get("authHome"),
-            )
-            run_info = {**run_info, "usage": usage, "usage_model": usage_model,
+            observation = _observe_headless_usage(run_session, run_info, baseline)
+            run_info = {**run_info, **observation,
+                        "parent_run_id": parsed.get("continue_run"),
+                        "conversation_id": extract_run_conversation_id(run_session.get("provider"), run_info.get("stdout_path"))
+                        or ((run_session.get("conversation") or {}).get("id") if run_session["provider"] == "claude" or parsed.get("continue_run") else None),
+                        "launch": run_session.get("launch"),
+                        "reasoning_effort": _launch_power(run_session),
                         "effective_model": (run_session.get("launch") or {}).get("model"),
                         "recovery_events": recovery_events}
             ctx["service"]["record_launch_history"](run_session["name"], {
@@ -718,6 +809,8 @@ def handle_run(rest, ctx):
                 "exit_code": run_info.get("returncode"),
                 **run_info,
             })
+            if parsed.get("continue_run"):
+                break
             if looks_model_at_capacity(run_session.get("provider"), run_info):
                 event = {"reason": "model_at_capacity", "attempt": attempt,
                          "session": run_session["name"], "model": models[model_index]}
@@ -883,11 +976,12 @@ def handle_run(rest, ctx):
         if run_info is not None:
             run_info = {**run_info, "recovery_events": locals().get("recovery_events", [])}
         if run_info and run_id and not getattr(error, "history_recorded", False):
-            usage, usage_model = extract_run_observation(
-                run_session.get("provider"), run_info.get("stdout_path"),
-                run_session.get("authHome"),
-            )
-            run_info = {**run_info, "usage": usage, "usage_model": usage_model}
+            observation = _observe_headless_usage(run_session, run_info, locals().get("baseline"))
+            run_info = {**run_info, **observation,
+                        "parent_run_id": parsed.get("continue_run"),
+                        "conversation_id": extract_run_conversation_id(run_session.get("provider"), run_info.get("stdout_path"))
+                        or ((run_session.get("conversation") or {}).get("id") if run_session["provider"] == "claude" or parsed.get("continue_run") else None),
+                        "launch": run_session.get("launch"), "reasoning_effort": _launch_power(run_session)}
             ctx["service"]["record_launch_history"](run_session["name"], {
                 "status": "failed",
                 "action": "run",

package/src/commands/status.py

@@ -53,10 +53,13 @@ from ..provider_runtime import (
 )
 from ..rtk_savings import rtk_saved
 from ..run_usage import (
-    USAGE_KEYS,
+    TOKEN_USAGE_KEYS,
+    cache_hit_ratio,
     estimate_cost,
+    format_cache_ratio,
     is_vouched,
     normalize_usage,
+    summarize_cache_usage,
     token_prices,
     weighted_usage,
 )
@@ -294,7 +297,9 @@ def _summarize_stats(entries):
             "reasoning_tokens": 0,
             "total_tokens": 0,
             "last_started_at": None,
+            "_entries": [],
         })
+        row["_entries"].append(entry)
         row["launches"] += 1
         if entry.get("provider"):
             row["provider"].add(entry["provider"])
@@ -315,7 +320,7 @@ def _summarize_stats(entries):
             usage = {}
         parsed_usage = {
             key: _token_value(usage, key)
-            for key in USAGE_KEYS
+            for key in TOKEN_USAGE_KEYS
         }
         if any(value is not None for value in parsed_usage.values()):
             row["usage_runs"] += 1
@@ -361,6 +366,16 @@ def _summarize_stats(entries):
         # overwhelming majority of cached tokens are, and weighting the whole
         # of it at the creation rate would overstate legacy sessions by more
         # than reading it as reads understates them.
+        group_entries = row.pop("_entries")
+        row["cache_usage"] = summarize_cache_usage(group_entries)
+        row["cache_hit_ratio"] = row["cache_usage"]["cache_hit_ratio"]
+        row["run_types"] = {
+            kind: {"runs": len(subset), **summarize_cache_usage(subset)}
+            for kind, subset in (
+                ("continued", [e for e in group_entries if e.get("parent_run_id")]),
+                ("cold", [e for e in group_entries if not e.get("parent_run_id")]),
+            )
+        }
         split = row["cache_creation_tokens"] + row["cache_read_tokens"]
         legacy_cache = max(0, row["cached_input_tokens"] - split)
         derived = normalize_usage(
@@ -381,15 +396,34 @@ def _summarize_stats(entries):
         reverse=True,
     )
 
+def _merge_cache_usage(summaries):
+    totals = {}
+    for key in ("input_tokens", "cache_creation_tokens", "cache_read_tokens", "output_tokens",
+                "measured_runs", "measured_input_tokens", "measured_cache_read_tokens"):
+        values = [s[key] for s in summaries if s[key] is not None]
+        totals[key] = sum(values) if values else (0 if key.startswith("measured_") else None)
+    inputs = totals["measured_input_tokens"]
+    totals["cache_hit_ratio"] = totals["measured_cache_read_tokens"] / inputs if inputs else None
+    return totals
+
+
 def _stats_totals(rows):
+    cache = _merge_cache_usage([row["cache_usage"] for row in rows])
     return {
+        "cache_usage": cache,
+        "cache_hit_ratio": cache["cache_hit_ratio"],
+        "run_types": {
+            kind: {"runs": sum(row["run_types"][kind]["runs"] for row in rows),
+                   **_merge_cache_usage([row["run_types"][kind] for row in rows])}
+            for kind in ("cold", "continued")
+        },
         "sessions": len(rows),
         "launches": sum(row["launches"] for row in rows),
         "successes": sum(row["successes"] for row in rows),
         "failures": sum(row["failures"] for row in rows),
         "duration_ms": sum(row["duration_ms"] for row in rows),
         "usage_runs": sum(row["usage_runs"] for row in rows),
-        **{key: sum(row[key] for row in rows) for key in USAGE_KEYS},
+        **{key: sum(row[key] for row in rows) for key in TOKEN_USAGE_KEYS},
         "weighted_tokens": sum(row["weighted_tokens"] for row in rows),
         "weighted_runs": sum(row["weighted_runs"] for row in rows),
         "unweighted_runs": sum(row["unweighted_runs"] for row in rows),
@@ -448,7 +482,7 @@ def _format_history(entries, use_color=False, active_sessions=None):
     active_sessions = active_sessions or set()
     if not entries:
         return "No launch history."
-    rows = [[_style(value, "1", use_color) for value in ["SESSION", "PROV.", "RESULT", "DURATION", "WHEN", "TRANSCRIPT"]]]
+    rows = [[_style(value, "1", use_color) for value in ["SESSION", "PROV.", "RESULT", "DURATION", "WHEN", "TOKENS", "TRANSCRIPT"]]]
     for entry in entries:
         transcript_path = entry.get("transcript_path")
         session_name = entry.get("session_name") or "-"
@@ -461,6 +495,8 @@ def _format_history(entries, use_color=False, active_sessions=None):
             _style(status, status_color, use_color),
             _style(_format_duration_ms(entry.get("duration_ms")), "33" if entry.get("duration_ms") else "2", use_color),
             _dim(_format_relative_age(entry.get("started_at")), use_color),
+            _dim(f"{_format_token_count((entry.get('usage') or {}).get('total_tokens'))} "
+                 f"{format_cache_ratio((entry.get('usage') or {}).get('cache_hit_ratio'))}", use_color),
             _dim(os.path.basename(transcript_path) if transcript_path else "-", use_color),
         ])
     return "\n".join([
@@ -529,10 +565,12 @@ def _format_stats(rows, totals, period=None, use_color=False, active_sessions=No
             _style(str(row["launches"]), "1", use_color),
             _style(str(row["usage_runs"]), "32" if row["usage_runs"] else "2", use_color),
             _style(_format_token_count(row["input_tokens"]), "96" if row["input_tokens"] else "2", use_color),
-            _style(_format_token_count(row["cached_input_tokens"]), "96" if row["cached_input_tokens"] else "2", use_color),
+            _style(_format_token_count(row["cached_input_tokens"]) if row["cache_usage"]["cache_read_tokens"] is not None
+                   or row["cache_usage"]["cache_creation_tokens"] is not None else "n/d",
+                   "96" if row["cached_input_tokens"] else "2", use_color),
             _style(_format_token_count(row["output_tokens"]), "96" if row["output_tokens"] else "2", use_color),
             _style(_format_token_count(row["reasoning_tokens"]), "95" if row["reasoning_tokens"] else "2", use_color),
-            _style(_format_token_count(row["total_tokens"]), "96" if row["total_tokens"] else "2", use_color),
+            _style(f"{_format_token_count(row['total_tokens'])} {format_cache_ratio(row.get('cache_hit_ratio'))}", "96" if row["total_tokens"] else "2", use_color),
             _style(_format_token_count(row["weighted_tokens"]) if row["weighted_runs"] else "-",
                    "1;95" if row["weighted_runs"] else "2", use_color),
             _style(_format_usd(row["cost_usd"]) if row["priced_runs"] else "-",
@@ -550,7 +588,7 @@ def _format_stats(rows, totals, period=None, use_color=False, active_sessions=No
         _dim(
             "Totals: "
             f"{totals['launches']} runs, {totals['usage_runs']} with usage, "
-            f"{_format_token_count(totals['total_tokens'])} tokens "
+            f"{_format_token_count(totals['total_tokens'])} tokens {format_cache_ratio(totals.get('cache_hit_ratio'))} "
             f"({_format_token_count(totals['weighted_tokens']) if totals['weighted_runs'] else '-'} cost-equivalent"
             + (f" on {totals['weighted_runs']}/{totals['usage_runs']} measured runs"
                if totals["usage_runs"] else "")
@@ -633,6 +671,9 @@ def handle_history(rest, ctx):
     limit = 0 if parsed["summary"] or has_period else parsed["limit"]
     entries = ctx["service"]["get_launch_history"](parsed["name"], limit=limit)
     entries = _filter_history_period(entries, parsed["period"])
+    entries = [{**entry, "parent_run_id": entry.get("parent_run_id"),
+                "usage": {**entry["usage"], "cache_hit_ratio": cache_hit_ratio(entry["usage"], provider=entry.get("provider")) if is_vouched(entry["usage"]) else None}
+                if isinstance(entry.get("usage"), dict) else entry.get("usage")} for entry in entries]
     if has_period and not parsed["summary"]:
         entries = entries[:parsed["limit"]]
     message = (

package/src/interactive_usage.py

@@ -261,9 +261,13 @@ def _codex_usage(handle):
             # larger than the input count is not a subset, so that record is
             # left alone rather than forced to zero.
             reported_input = _number(usage.get("input_tokens"))
-            cache_read = _number(usage.get("cached_input_tokens"))
+            cache_read = _number(usage["cached_input_tokens"]) if usage.get("cached_input_tokens") is not None else None
+            cache_write = _number(usage["cache_write_input_tokens"]) if usage.get("cache_write_input_tokens") is not None else None
+            cached = (cache_read or 0) + (cache_write or 0)
             latest = normalize_usage(
-                input_tokens=reported_input - cache_read if cache_read <= reported_input else reported_input,
+                provider="codex",
+                input_tokens=reported_input - cached if cached <= reported_input else reported_input,
+                cache_creation_tokens=cache_write,
                 cache_read_tokens=cache_read,
                 output_tokens=_number(usage.get("output_tokens")),
                 reasoning_tokens=_number(usage.get("reasoning_output_tokens")) or None,
@@ -286,6 +290,7 @@ def _claude_usage(handle):
     inside `output_tokens` -- so that field stays absent by design.
     """
     totals = {"input_tokens": 0, "cache_creation_tokens": 0, "cache_read_tokens": 0, "output_tokens": 0}
+    missing = set(totals)
     long_ttl = None
     seen = set()
     model = None
@@ -301,6 +306,11 @@ def _claude_usage(handle):
                 if identifier in seen:
                     continue
                 seen.add(identifier)
+            for source, target in (("input_tokens", "input_tokens"), ("output_tokens", "output_tokens"),
+                                   ("cache_creation_input_tokens", "cache_creation_tokens"),
+                                   ("cache_read_input_tokens", "cache_read_tokens")):
+                if usage.get(source) is not None:
+                    missing.discard(target)
             totals["input_tokens"] += _number(usage.get("input_tokens"))
             totals["cache_creation_tokens"] += _number(usage.get("cache_creation_input_tokens"))
             totals["cache_read_tokens"] += _number(usage.get("cache_read_input_tokens"))
@@ -316,7 +326,8 @@ def _claude_usage(handle):
             continue
     if not seen and not any(totals.values()):
         return None, model
-    return normalize_usage(**totals, cache_creation_1h_tokens=long_ttl), model
+    return normalize_usage(**{k: None if k in missing else v for k, v in totals.items()},
+                           cache_creation_1h_tokens=long_ttl), model
 
 
 def _number(value):
@@ -326,7 +337,7 @@ def _number(value):
         return 0
 
 
-#: The quantities a provider actually reports. The other two fields of a usage
+#: The quantities a provider actually reports. The other fields of a usage
 #: record are derived by `normalize_usage` and must never be differenced.
 MEASURED_KEYS = (
     "input_tokens",
@@ -338,7 +349,7 @@ MEASURED_KEYS = (
 )
 
 
-def usage_delta(cumulative, previous):
+def usage_delta(cumulative, previous, provider=None):
     """What this run added to a transcript that already held `previous`.
 
     Both readers return a *cumulative* figure: Claude's is the sum over the
@@ -372,7 +383,7 @@ def usage_delta(cumulative, previous):
         if difference < 0:
             return None
         parts[key] = difference
-    return normalize_usage(**parts)
+    return normalize_usage(**parts, provider=provider)
 
 
 def transcript_predates_run(path, started_at):

package/src/provider_background.py

@@ -224,6 +224,7 @@ def read_transcript_outcome(path):
     if not path:
         return outcome
     totals = {"input_tokens": 0, "cache_creation_tokens": 0, "cache_read_tokens": 0, "output_tokens": 0}
+    missing = set(totals)
     long_ttl = None
     # This path had no de-duplication at all, so a transcript that records the
     # same billed response more than once inflated the total outright.
@@ -266,6 +267,11 @@ def read_transcript_outcome(path):
                     seen = True
                     if isinstance(message.get("model"), str) and message["model"]:
                         models.add(message["model"])
+                    for source, target in (("input_tokens", "input_tokens"), ("output_tokens", "output_tokens"),
+                                           ("cache_creation_input_tokens", "cache_creation_tokens"),
+                                           ("cache_read_input_tokens", "cache_read_tokens")):
+                        if usage.get(source) is not None:
+                            missing.discard(target)
                     totals["input_tokens"] += usage.get("input_tokens") or 0
                     totals["cache_creation_tokens"] += usage.get("cache_creation_input_tokens") or 0
                     totals["cache_read_tokens"] += usage.get("cache_read_input_tokens") or 0
@@ -276,7 +282,8 @@ def read_transcript_outcome(path):
     except OSError:
         return outcome
     if seen:
-        outcome["usage"] = normalize_usage(**totals, cache_creation_1h_tokens=long_ttl)
+        outcome["usage"] = normalize_usage(**{k: None if k in missing else v for k, v in totals.items()},
+                                           cache_creation_1h_tokens=long_ttl)
         if len(models) == 1:
             outcome["usage_model"] = next(iter(models))
     return outcome

package/src/provider_runtime.py

@@ -1006,7 +1006,7 @@ def _build_headless_launch_spec(session, cwd=None, env_override=None, initial_pr
         args = ["--print", "--output-format", "json"]
         conversation_id = _conversation_id(session)
         if conversation_id:
-            args += ["--session-id", conversation_id]
+            args += ["--resume" if session.get("continue_run") else "--session-id", conversation_id]
         if model:
             args += ["--model", _claude_cli_model(model)]
         # --max-budget-usd and --fallback-model are --print-only in the claude
@@ -1045,6 +1045,8 @@ def _build_headless_launch_spec(session, cwd=None, env_override=None, initial_pr
         if permission:
             args += HEADLESS_CODEX_PERMISSION_ARGS.get(permission, [])
         args += preference_args
+        if session.get("continue_run"):
+            args += ["resume", _conversation_id(session)]
         if initial_prompt:
             # `--` keeps a prompt that starts with `-` from being read as an option.
             args += ["--", initial_prompt]

package/src/run_command.py

@@ -55,6 +55,14 @@ def run_cdx_error_code(error):
     return "cdx_error"
 
 
+def run_conversation_id(session, run_info=None):
+    if run_info is not None and "conversation_id" in run_info:
+        return run_info["conversation_id"]
+    if (session or {}).get("provider") == "codex" and not session.get("continue_run"):
+        return None
+    return ((session or {}).get("conversation") or {}).get("id")
+
+
 def run_payload_reasoning_effort(parsed, session):
     launch = (session.get("launch") or {}) if session else {}
     return (
@@ -149,7 +157,7 @@ def run_warnings(parsed, session, selection_row=None):
 
 
 def run_launch_payload(api_schema_version, parsed, session, artifacts, cwd=None,
-                       pid=None, launch_log_path=None, selection_row=None):
+                       pid=None, launch_log_path=None, selection_row=None, conversation_id=None):
     """Payload for a detached launch: identity and artifact paths, no outcome.
 
     Deliberately shaped like `run_result_payload` minus the fields only a
@@ -161,6 +169,8 @@ def run_launch_payload(api_schema_version, parsed, session, artifacts, cwd=None,
         "ok": True,
         "action": "run",
         "launcher": "cdx",
+        "parent_run_id": parsed.get("continue_run"),
+        "conversation_id": conversation_id or run_conversation_id(session),
         "detached": True,
         "session": session.get("name") if session else None,
         "provider": session.get("provider") if session else parsed.get("provider"),
@@ -208,6 +218,8 @@ def run_result_payload(api_schema_version, ok, parsed, session, run_info=None,
         "ok": bool(ok),
         "action": "run",
         "launcher": "cdx",
+        "parent_run_id": parsed.get("continue_run"),
+        "conversation_id": run_conversation_id(session, run_info),
         "session": session.get("name") if session else None,
         "provider": session.get("provider") if session else parsed.get("provider"),
         "model": run_info.get("effective_model", parsed.get("model") or ((session.get("launch") or {}).get("model") if session else None)),

package/src/run_registry.py

@@ -243,7 +243,8 @@ class RunRegistry:
         with _registry_lock(self.path):
             _check_capacity(_read_registry(self.path), max_parallel)
 
-    def start(self, run_id, *, kind, session, provider, model, cwd, artifacts=None, label=None, max_parallel=None):
+    def start(self, run_id, *, kind, session, provider, model, cwd, artifacts=None, label=None, max_parallel=None,
+              parent_run_id=None, conversation_id=None, launch=None, reasoning_effort=None):
         with _registry_lock(self.path):
             data = _read_registry(self.path)
             data["runs"] = [run for run in data["runs"] if run.get("run_id") != run_id]
@@ -252,6 +253,8 @@ class RunRegistry:
                 # detached child writes a second time under the same id.
                 _check_capacity(data, max_parallel)
             record = _base_record(run_id, kind=kind, session=session, provider=provider, model=model, cwd=cwd, artifacts=artifacts)
+            record.update(parent_run_id=parent_run_id, conversation_id=conversation_id,
+                          launch=dict(launch or {}), reasoning_effort=reasoning_effort)
             if label:
                 record["label"] = label
             data["runs"].insert(0, record)
@@ -285,6 +288,8 @@ class RunRegistry:
                     continue
                 run["background_path"] = path
                 run["provider_session_id"] = provider_session_id
+                if provider_session_id:
+                    run["conversation_id"] = provider_session_id
                 run["provider_agent_id"] = provider_agent_id
                 _write_registry(self.path, data)
                 return run
@@ -356,6 +361,8 @@ class RunRegistry:
                     run["duration_seconds"] = None
             if run_info:
                 run["pid"] = run_info.get("pid")
+                if run_info.get("launch"):
+                    run["launch"] = run_info["launch"]
                 run["exit_code"] = run_info.get("returncode")
                 run["artifacts"] = {
                     **(run.get("artifacts") or {}),
@@ -367,8 +374,12 @@ class RunRegistry:
                 # Normalize on the way in, not on the way out: this record is
                 # what `cdx run-status` and `cdx run-report` publish, and it
                 # used to store whichever shape the producing reader emitted.
-                run["usage"] = coerce_usage(final_payload.get("usage"))
+                run["usage"] = coerce_usage(final_payload.get("usage"), provider=run.get("provider"))
                 run["usage_model"] = final_payload.get("usage_model")
+                run["conversation_id"] = final_payload.get("conversation_id") or run.get("conversation_id")
+                run["parent_run_id"] = final_payload.get("parent_run_id") or run.get("parent_run_id")
+                if "reasoning_effort" in final_payload:
+                    run["reasoning_effort"] = final_payload["reasoning_effort"]
                 run["model"] = final_payload.get("model")
                 run["final_payload"] = final_payload
             if error:

package/src/run_usage.py

@@ -24,6 +24,9 @@ The definitions below are therefore normative, not a suggestion:
                         published field of `cdx run --json`, and because the
                         stats table shows one CACHE column. It is a derived
                         sum, never a source.
+  cache_hit_ratio       cache_read / (input + cache_creation + cache_read).
+                        None when input, reads, or writes are unreported (except
+                        Codex writes), or total input is zero.
   output_tokens         Generated tokens.
   reasoning_tokens      Reasoning counted separately by the provider. Codex
                         reports one; Claude does not and never will -- it bills
@@ -40,7 +43,7 @@ differently -- 1.25x (2x for a one-hour TTL) and 0.1x of uncached input -- and
 a weighted figure cannot recover the split once they are summed.
 
 Absence stays absent: `None` means "not reported", which is not zero. Only
-`normalize_usage` may derive `cached_input_tokens` and `total_tokens`, so no
+`normalize_usage` derives the cache sum, total, and hit ratio, so no
 caller can invent a fourth arithmetic.
 """
 
@@ -50,7 +53,7 @@ import math
 from .errors import CdxError
 
 #: Order matters only for readability; every consumer addresses these by name.
-USAGE_KEYS = (
+TOKEN_USAGE_KEYS = (
     "input_tokens",
     "cached_input_tokens",
     "cache_creation_tokens",
@@ -60,17 +63,18 @@ USAGE_KEYS = (
     "reasoning_tokens",
     "total_tokens",
 )
-#: The two fields `normalize_usage` derives. Never read them from a provider.
-DERIVED_USAGE_KEYS = ("cached_input_tokens", "total_tokens")
+USAGE_KEYS = (*TOKEN_USAGE_KEYS, "cache_hit_ratio")
+#: Derived values are never read from a provider.
+DERIVED_USAGE_KEYS = ("cached_input_tokens", "total_tokens", "cache_hit_ratio")
 SUPPORTED_PROVIDERS = {"claude", "codex"}
 
 
 def empty_usage():
-    return {key: None for key in USAGE_KEYS}
+    return dict.fromkeys(USAGE_KEYS)
 
 
 def normalize_usage(input_tokens=None, cache_creation_tokens=None, cache_read_tokens=None,
-                    output_tokens=None, reasoning_tokens=None, cache_creation_1h_tokens=None):
+                    output_tokens=None, reasoning_tokens=None, cache_creation_1h_tokens=None, provider=None):
     """Build a usage record from the four measured quantities.
 
     The derived fields are computed here and only here. A record whose parts are
@@ -98,7 +102,50 @@ def normalize_usage(input_tokens=None, cache_creation_tokens=None, cache_read_to
         parts["cache_read_tokens"],
         parts["output_tokens"],
     )
-    return {**parts, "cached_input_tokens": cached, "total_tokens": total}
+    return {**parts, "cached_input_tokens": cached, "total_tokens": total,
+            "cache_hit_ratio": cache_hit_ratio(parts, provider=provider)}
+
+
+def cache_hit_ratio(usage, provider=None):
+    """Cache reads divided by all input, or None without a reported read split.
+
+    Missing writes leave Claude's denominator unknown. Only Codex can recover
+    the denominator from its cache-inclusive input total when writes are absent.
+    An empty input has no defined hit ratio.
+    """
+    read = _non_negative(usage.get("cache_read_tokens"))
+    uncached = _non_negative(usage.get("input_tokens"))
+    writes = _non_negative(usage.get("cache_creation_tokens"))
+    if read is None or uncached is None or (writes is None and provider != "codex"):
+        return None
+    total = uncached + read + (writes or 0)
+    return read / total if total else None
+
+
+def summarize_cache_usage(entries):
+    """Nullable measured sums and an input-weighted ratio over covered runs."""
+    keys = ("input_tokens", "cache_creation_tokens", "cache_read_tokens", "output_tokens")
+    sums = dict.fromkeys(keys)
+    reads = inputs = measured = 0
+    for entry in entries:
+        usage = entry.get("usage") or {}
+        if not is_vouched(usage):
+            continue
+        usage = coerce_usage(usage, provider=entry.get("provider"))
+        for key in keys:
+            value = usage.get(key)
+            if value is not None:
+                sums[key] = (sums[key] or 0) + value
+        if usage["cache_hit_ratio"] is not None:
+            measured += 1
+            reads += usage["cache_read_tokens"]
+            inputs += usage["input_tokens"] + usage["cache_read_tokens"] + (usage.get("cache_creation_tokens") or 0)
+    return {**sums, "cache_hit_ratio": reads / inputs if inputs else None,
+            "measured_runs": measured, "measured_input_tokens": inputs, "measured_cache_read_tokens": reads}
+
+
+def format_cache_ratio(ratio):
+    return "cache n/d" if ratio is None else f"cache {ratio * 100:.0f} %"
 
 
 #: What a cached token costs relative to one uncached input token.
@@ -370,7 +417,7 @@ def is_vouched(usage):
     return isinstance(usage, dict) and "cache_creation_tokens" in usage
 
 
-def coerce_usage(usage):
+def coerce_usage(usage, provider=None):
     """Bring an already-built usage record onto the canonical shape.
 
     For boundaries that receive a record rather than measure one -- the run
@@ -382,6 +429,7 @@ def coerce_usage(usage):
     if not isinstance(usage, dict):
         return None
     record = normalize_usage(
+        provider=provider,
         input_tokens=usage.get("input_tokens"),
         cache_creation_tokens=usage.get("cache_creation_tokens"),
         cache_read_tokens=usage.get("cache_read_tokens"),
@@ -409,6 +457,20 @@ def _sum_present(*values):
     return sum(present)
 
 
+def extract_run_conversation_id(provider, stdout_path):
+    """Read identity from this run's output, never from transcript recency."""
+    if not stdout_path:
+        return None
+    try:
+        with open(stdout_path, encoding="utf-8", errors="replace") as handle:
+            records = _parse_json_records(handle.read())
+    except OSError:
+        return None
+    key = "thread_id" if provider == "codex" else "session_id"
+    ids = {r[key] for r in records if isinstance(r, dict) and isinstance(r.get(key), str) and r[key]}
+    return next(iter(ids)) if len(ids) == 1 else None
+
+
 def extract_run_usage(provider, stdout_path):
     return extract_run_observation(provider, stdout_path)[0]
 
@@ -430,7 +492,7 @@ def extract_run_observation(provider, stdout_path, auth_home=None):
     if not records:
         return empty_usage(), None
 
-    usage = _extract_usage_from_records(records)
+    usage = _extract_usage_from_records(records, provider=provider)
     if not _has_usage(usage):
         return empty_usage(), None
     models = set()
@@ -439,7 +501,7 @@ def extract_run_observation(provider, stdout_path, auth_home=None):
             continue
         message = record.get("message")
         model = record.get("model") or (message.get("model") if isinstance(message, dict) else None)
-        if isinstance(model, str) and model and _has_usage(_find_usage(record)):
+        if isinstance(model, str) and model and _has_usage(_find_usage(record, provider=provider)):
             models.add(model)
         model_usage = record.get("modelUsage")
         if isinstance(model_usage, dict):
@@ -505,33 +567,33 @@ def _parse_json_records(text):
     return records
 
 
-def _extract_usage_from_records(records):
+def _extract_usage_from_records(records, provider=None):
     latest = None
     for record in records:
-        candidate = _find_usage(record)
+        candidate = _find_usage(record, provider=provider)
         if _has_usage(candidate):
             latest = candidate
     return latest or empty_usage()
 
 
-def _find_usage(value):
+def _find_usage(value, provider=None):
     if isinstance(value, dict):
-        direct = _usage_from_dict(value)
+        direct = _usage_from_dict(value, provider=provider)
         if _has_usage(direct):
             return direct
         for child in value.values():
-            found = _find_usage(child)
+            found = _find_usage(child, provider=provider)
             if _has_usage(found):
                 return found
     if isinstance(value, list):
         for child in value:
-            found = _find_usage(child)
+            found = _find_usage(child, provider=provider)
             if _has_usage(found):
                 return found
     return empty_usage()
 
 
-def _usage_from_dict(value):
+def _usage_from_dict(value, provider=None):
     """Map one provider usage object onto the canonical fields.
 
     This used to fold the cache counts into `input_tokens` *and* report them
@@ -544,16 +606,18 @@ def _usage_from_dict(value):
         return empty_usage()
 
     cache_creation = _first_int(usage.get("cache_creation_input_tokens"))
+    if cache_creation is None:
+        cache_creation = _first_int(usage.get("cache_write_input_tokens"))
     cache_read = _first_int(usage.get("cache_read_input_tokens"))
-    if cache_creation is None and cache_read is None:
-        # Codex reports one cached figure with no creation/read split; it is a
-        # read by construction, since nothing else could have written it.
+    if cache_read is None:
+        # Codex's cached input count measures reads, independently of writes.
         cache_read = _first_int(usage.get("cached_input_tokens"))
 
     input_tokens = _int_value(usage.get("input_tokens"), usage.get("prompt_tokens"))
     input_tokens = _uncached_input(input_tokens, cache_read, usage)
 
     return normalize_usage(
+        provider=provider,
         input_tokens=input_tokens,
         cache_creation_tokens=cache_creation,
         cache_creation_1h_tokens=_nested_int(usage, "cache_creation", "ephemeral_1h_input_tokens"),
@@ -583,17 +647,18 @@ def _uncached_input(input_tokens, cache_read, usage):
     Guessing wrong in that direction would silently erase real input tokens,
     which is the failure this whole definition exists to stop.
     """
-    if input_tokens is None or not cache_read:
+    if input_tokens is None:
         return input_tokens
     if usage.get("cache_creation_input_tokens") is not None:
         return input_tokens
     if usage.get("cache_read_input_tokens") is not None:
         return input_tokens
-    if usage.get("cached_input_tokens") is None:
+    if usage.get("cached_input_tokens") is None and usage.get("cache_write_input_tokens") is None:
         return input_tokens
-    if cache_read > input_tokens:
+    cached = (cache_read or 0) + (_first_int(usage.get("cache_write_input_tokens")) or 0)
+    if cached > input_tokens:
         return input_tokens
-    return input_tokens - cache_read
+    return input_tokens - cached
 
 
 def _nested_int(value, parent, child):