cdx-manager 0.21.6 → 0.23.0

package/src/provider_background.py

@@ -72,12 +72,13 @@ def supports_native_background(provider, env=None, spawn_sync=None):
     1. A delegated run cannot honour the `cdx run --json` contract. The
        in-house path runs `claude --print --output-format json` and gets a
        structured result, token usage, and a final payload. `--bg` runs the
-       interactive TUI; `claude logs <id>` returns an ANSI screen dump. So
-       usage accounting, the final payload, and the rate-limit classification
-       that `--failover` depends on all have no source.
-    2. Nothing yet drives a delegated run to a terminal status. `agent_terminal_status`
-       exists but no caller consults the provider, so the record relies on pid
-       liveness and a blocked agent reads as running indefinitely.
+       interactive TUI; `claude logs <id>` returns an ANSI screen dump. Usage
+       and the final text are read back from the session transcript, but the
+       rate-limit classification that `--failover` depends on has no source.
+    2. A delegated run only reaches a terminal status when a caller reads it:
+       `_reconcile_background_runs` in commands/runs.py consults the
+       transcript, then `agent_terminal_status`, on `cdx runs`, `run-status`
+       and `run-report`. Until one of those runs, the record stays `running`.
     3. cdx's own launch spec makes the agent block. A hand-run
        `claude --bg --permission-mode bypassPermissions "..."` reaches
        `state: done`; the same task launched through cdx sits at
@@ -223,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}
+    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.
     counted = set()
@@ -268,10 +270,13 @@ def read_transcript_outcome(path):
                     totals["cache_creation_tokens"] += usage.get("cache_creation_input_tokens") or 0
                     totals["cache_read_tokens"] += usage.get("cache_read_input_tokens") or 0
                     totals["output_tokens"] += usage.get("output_tokens") or 0
+                    split = usage.get("cache_creation")
+                    if isinstance(split, dict) and "ephemeral_1h_input_tokens" in split:
+                        long_ttl = (long_ttl or 0) + (split["ephemeral_1h_input_tokens"] or 0)
     except OSError:
         return outcome
     if seen:
-        outcome["usage"] = normalize_usage(**totals)
+        outcome["usage"] = normalize_usage(**totals, cache_creation_1h_tokens=long_ttl)
         if len(models) == 1:
             outcome["usage_model"] = next(iter(models))
     return outcome

package/src/provider_runtime.py

@@ -150,6 +150,10 @@ CLAUDE_PARENT_SESSION_ENV = (
     "CLAUDE_CODE_MESSAGING_SOCKET",
     "CLAUDE_CODE_MESSAGING_TOKEN",
     "CLAUDE_PID",
+    # Credentials: a profile launched from inside another profile's session must
+    # not inherit that account's token. The profile's own token is set after.
+    "CLAUDE_CODE_OAUTH_TOKEN",
+    "ANTHROPIC_API_KEY",
 )
 CLAUDE_CLI_MODEL_ALIASES = {
     "claude-sonnet": "sonnet",
@@ -208,6 +212,40 @@ def _shared_tool_cache_overrides(env):
     }
 
 
+def operator_rtk_history_path(env=None):
+    """The rtk history database of the operator's real home.
+
+    rtk files its savings under the data dir of HOME, and a profile launch
+    swaps HOME, so each account kept its own history.db and `rtk gain` in the
+    operator's shell saw none of what the agents saved. Read from the passwd
+    entry rather than HOME, which is already a profile home when cdx runs
+    inside a session.
+    """
+    env = os.environ if env is None else env
+    if os.name == "nt":
+        base = env.get("LOCALAPPDATA")
+        return os.path.join(base, "rtk", "history.db") if base else None
+    import pwd
+
+    try:
+        home = pwd.getpwuid(os.getuid()).pw_dir
+    except KeyError:
+        # A uid without a passwd entry (common in containers): no better
+        # answer than HOME.
+        home = env.get("HOME") or os.path.expanduser("~")
+    if sys.platform == "darwin":
+        return os.path.join(home, "Library", "Application Support", "rtk", "history.db")
+    data_home = env.get("XDG_DATA_HOME") or os.path.join(home, ".local", "share")
+    return os.path.join(data_home, "rtk", "history.db")
+
+
+def _shared_rtk_history(env):
+    """Point every profile's rtk at one history, unless the operator chose one."""
+    path = None if env.get("RTK_DB_PATH") else operator_rtk_history_path(env)
+    if path:
+        env["RTK_DB_PATH"] = path
+
+
 def _anthropic_profile_name():
     return "default"
 
@@ -542,6 +580,9 @@ def _wrap_launch_with_transcript(session, spec, capture_transcript=True, env=Non
     script_args = env.get("CDX_SCRIPT_ARGS")
     transcript_path = _build_launch_transcript_path(session)
     os.makedirs(os.path.dirname(transcript_path), exist_ok=True)
+    if os.name != "nt":
+        # script(1) keeps an existing file's mode, and a transcript can hold a token.
+        os.close(os.open(transcript_path, os.O_CREAT | os.O_WRONLY, 0o600))
     if script_args:
         args = shlex.split(script_args)
         if "{transcript}" in args:
@@ -674,12 +715,15 @@ def _build_launch_spec(session, cwd=None, env_override=None, initial_prompt=None
     env = {**os.environ, **env_override}
     for key, value in _shared_tool_cache_overrides(env).items():
         env.setdefault(key, value)
+    _shared_rtk_history(env)
     env.update(launch_notify_env(session, notifications_enabled(session)))
     env.update(_scrub_env(session))
     preference_args = _launch_preference_args(session, env=env)
     if session["provider"] == PROVIDER_CLAUDE:
         launch = session.get("launch") or {}
-        args = ["--name", session["name"]]
+        # No --name: it would title every conversation after the account in
+        # the /resume picker. The account already shows in cdx's terminal title.
+        args = []
         conversation_id = _conversation_id(session)
         if conversation_id:
             args += ["--session-id", conversation_id]
@@ -776,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")
@@ -850,6 +906,7 @@ def _build_resume_spec(session, cwd=None, env_override=None, capture_transcript=
     cwd = cwd or os.getcwd()
     env_override = env_override or {}
     env = {**os.environ, **env_override}
+    _shared_rtk_history(env)
     capability = get_resume_capability(session, cwd=cwd)
     if not capability["resumable"]:
         raise CdxError(f"Provider {session.get('provider')} does not support native resume through cdx.")
@@ -869,7 +926,7 @@ def _build_resume_spec(session, cwd=None, env_override=None, capture_transcript=
             if capability["strategy"] == "provider_conversation_id"
             else ["--continue"]
         )
-        args += ["--name", session["name"]]
+        # No --name: on a resume it would overwrite the user's /rename.
         if launch.get("model"):
             args += ["--model", _claude_cli_model(launch["model"])]
         args += _launch_config_args(session)
@@ -926,6 +983,7 @@ def _build_headless_launch_spec(session, cwd=None, env_override=None, initial_pr
     _validate_initial_prompt(initial_prompt)
     cwd = cwd or os.getcwd()
     env = {**os.environ, **(env_override or {})}
+    _shared_rtk_history(env)
     # Headless runs read the same home, and so the same hooks, as an interactive
     # launch. Their caller already learns of completion from the return value.
     env.update(launch_notify_env(session, enabled=False))
@@ -937,7 +995,7 @@ def _build_headless_launch_spec(session, cwd=None, env_override=None, initial_pr
     model = launch.get("model")
 
     if session["provider"] == PROVIDER_CLAUDE:
-        args = ["--print", "--output-format", "json", "--name", session["name"]]
+        args = ["--print", "--output-format", "json"]
         conversation_id = _conversation_id(session)
         if conversation_id:
             args += ["--session-id", conversation_id]

package/src/retro.py

@@ -0,0 +1,131 @@
+"""Session retrospectives: what the user had to correct, so the next session knows it.
+
+With `cdx set <name> --retro on`, the end of an interactive session starts a
+detached, read-only `cdx run --kind retro` on a ready account. It reads the
+session's transcript and reports the corrections the user made and the lessons
+worth keeping, each with where it belongs (memory, runbook, skill, CLAUDE.md).
+It changes nothing: `cdx retro` shows the reports, and the user decides.
+"""
+
+import json
+import os
+import shutil
+import subprocess
+
+#: A session with fewer prompts than this rarely holds a correction worth a model call.
+MIN_USER_PROMPTS = 3
+
+PROMPT = """You are writing a retrospective of one finished coding-agent session. Do not modify any file.
+
+Transcript (JSONL, possibly large; read it in bounded portions, never all at once): {transcript}
+Project folder: {cwd}
+
+Find the moments where the user corrected, redirected or overruled the agent, and the
+non-obvious facts the session had to discover. Ignore routine back-and-forth.
+
+Answer in Markdown with exactly these sections:
+## Corrections
+One bullet per correction: what the agent did, what the user wanted, in one line each.
+## Lessons
+One bullet per lesson worth keeping for future sessions, each starting with where it belongs:
+`memory:`, `runbook:`, `skill:` or `CLAUDE.md:`, followed by the exact text to add.
+## Verdict
+One line: "nothing to learn" if both sections are empty, else the single most useful lesson.
+"""
+
+
+def enabled(session):
+    return (session.get("launch") or {}).get("retro") is True
+
+
+def start(session, cwd, transcript, env=None, popen=subprocess.Popen):
+    """Start the retro run in the background; returns the argv, or None when skipped."""
+    env = {**os.environ, **(env or {})}
+    if not enabled(session) or not transcript or not os.path.isfile(transcript):
+        return None
+    if env.get("CDX_RETRO") == "1" or _user_prompts(transcript) < MIN_USER_PROMPTS:
+        return None
+    executable = env.get("CDX_BIN") or shutil.which("cdx", path=env.get("PATH")) or "cdx"
+    argv = [
+        executable, "run", "--provider", session["provider"], "--cwd", cwd, "--kind", "retro",
+        "--permission", "read-only", "--power", "low", "--detach", "--json",
+        "--prompt", PROMPT.format(transcript=transcript, cwd=cwd),
+    ]
+    env["CDX_RETRO"] = "1"  # a retro never asks for a retro of itself
+    try:
+        popen(argv, env=env, stdin=subprocess.DEVNULL, stdout=subprocess.DEVNULL,
+              stderr=subprocess.DEVNULL, start_new_session=True)
+    except OSError:
+        return None
+    return argv
+
+
+def _user_prompts(transcript):
+    """Prompts the user typed: Claude `user` records that are not tool results, Codex `user_message` events.
+
+    Size is no proxy: one long handoff prompt makes a large transcript of a session
+    that never started.
+    """
+    count = 0
+    try:
+        with open(transcript, encoding="utf-8", errors="replace") as handle:
+            for line in handle:
+                if ('"type":"user"' in line and '"tool_result"' not in line) or '"type":"user_message"' in line:
+                    count += 1
+                    if count >= MIN_USER_PROMPTS:
+                        break
+    except OSError:
+        return 0
+    return count
+
+
+def reports(registry, limit=5):
+    """The newest retro runs, newest first, with their text when finished."""
+    found = []
+    for run in registry.list(limit=200):
+        if run.get("kind") != "retro":
+            continue
+        payload = run.get("final_payload") if isinstance(run.get("final_payload"), dict) else {}
+        found.append({"run_id": run.get("run_id"), "status": run.get("status"), "cwd": run.get("cwd"),
+                      "started_at": run.get("started_at"), "session": run.get("session"),
+                      "report": _result_text(payload.get("stdout_path"))})
+        if len(found) >= limit:
+            break
+    return found
+
+
+def _result_text(stdout_path):
+    """The answer of a finished run: Claude's `result`, else where to read it."""
+    if not stdout_path or not os.path.isfile(stdout_path):
+        return None
+    try:
+        with open(stdout_path, encoding="utf-8") as handle:
+            document = json.load(handle)
+    except (OSError, ValueError):
+        return f"(see {stdout_path})"
+    result = document.get("result") if isinstance(document, dict) else None
+    return result if isinstance(result, str) else f"(see {stdout_path})"
+
+
+def handle_retro(rest, ctx):
+    from .cli_helpers import _json_success, _write_json
+    from .errors import CdxError
+    from .run_registry import RunRegistry
+
+    json_flag = "--json" in rest
+    args = [arg for arg in rest if arg != "--json"]
+    limit = 5
+    if args[:1] == ["--limit"] and len(args) == 2 and args[1].isdigit():
+        limit = int(args[1])
+    elif args:
+        raise CdxError("Usage: cdx retro [--limit N] [--json]")
+    found = reports(RunRegistry(ctx["service"]["base_dir"]), limit=limit)
+    if json_flag:
+        _write_json(ctx, _json_success("retro", f"{len(found)} retro(s)", retros=found))
+        return 0
+    if not found:
+        ctx["out"]("No session retro yet. Turn them on with `cdx set <name> --retro on`.\n")
+        return 0
+    for item in found:
+        ctx["out"](f"## {item['started_at']} · {item['cwd']} · {item['status']}\n{item['report'] or '(still running)'}\n\n")
+    return 0

package/src/rtk_savings.py

@@ -0,0 +1,68 @@
+"""What rtk saved, for the period `cdx stats` reports on.
+
+Launches share the operator's rtk history (RTK_DB_PATH), but profiles used before
+that kept their own `history.db` under their home; both are read so older
+savings are not lost. rtk itself does the reading (`rtk gain --daily --format
+json`), so this never depends on its database schema.
+"""
+
+import glob
+import json
+import os
+import shutil
+import subprocess
+from datetime import datetime
+
+from .provider_runtime import operator_rtk_history_path
+
+_PROFILE_DBS = (
+    ("*", "Library", "Application Support", "rtk", "history.db"),
+    ("*", "*-home", "Library", "Application Support", "rtk", "history.db"),
+    ("*", ".local", "share", "rtk", "history.db"),
+    ("*", "*-home", ".local", "share", "rtk", "history.db"),
+)
+
+
+def history_databases(base_dir, env=None):
+    """Every rtk history this operator's sessions wrote to, the shared one first."""
+    env = os.environ if env is None else env
+    found = []
+    for path in [env.get("RTK_DB_PATH") or operator_rtk_history_path(env)] + [
+        match for pattern in _PROFILE_DBS
+        for match in sorted(glob.glob(os.path.join(glob.escape(os.path.join(base_dir, "profiles")), *pattern)))
+    ]:
+        if path and os.path.isfile(path) and os.path.realpath(path) not in {os.path.realpath(p) for p in found}:
+            found.append(path)
+    return found
+
+
+def _in_period(day, period):
+    for key, keep in (("from", lambda d, edge: d >= edge), ("to", lambda d, edge: d <= edge)):
+        edge = (period or {}).get(key)
+        if edge and not keep(day, datetime.fromisoformat(edge).date().isoformat()):
+            return False
+    return True
+
+
+def rtk_saved(base_dir, period=None, env=None, run=subprocess.run):
+    """{commands, input_tokens, saved_tokens, databases} over the period, or None without rtk."""
+    env = {**os.environ, **(env or {})}
+    rtk = shutil.which("rtk", path=env.get("PATH"))
+    databases = history_databases(base_dir, env)
+    if not rtk or not databases:
+        return None
+    totals = {"commands": 0, "input_tokens": 0, "saved_tokens": 0, "databases": 0}
+    for database in databases:
+        try:
+            result = run([rtk, "gain", "--daily", "--format", "json"], env={**env, "RTK_DB_PATH": database},
+                         capture_output=True, text=True, timeout=15, check=False)
+            days = json.loads(result.stdout).get("daily") or []
+        except (OSError, ValueError, AttributeError, subprocess.TimeoutExpired):
+            continue
+        totals["databases"] += 1
+        for day in days:
+            if isinstance(day, dict) and _in_period(str(day.get("date")), period):
+                totals["commands"] += int(day.get("commands") or 0)
+                totals["input_tokens"] += int(day.get("input_tokens") or 0)
+                totals["saved_tokens"] += int(day.get("saved_tokens") or 0)
+    return totals if totals["databases"] else None

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
 
 
@@ -219,15 +219,41 @@ def _base_record(run_id, *, kind, session, provider, model, cwd, artifacts=None)
     }
 
 
+def _check_capacity(data, max_parallel):
+    _refresh_stale_runs(data)
+    running = sum(1 for run in data["runs"] if run.get("status") == "running")
+    if running >= max_parallel:
+        raise CdxError(
+            f"{running} run(s) already running, the limit is {max_parallel}. "
+            "Wait for one to finish (cdx runs --json) or raise --max-parallel.",
+            code="too_many_runs",
+        )
+
+
 class RunRegistry:
     def __init__(self, base_dir):
         self.path = registry_path(base_dir)
 
-    def start(self, run_id, *, kind, session, provider, model, cwd, artifacts=None):
+    def check_capacity(self, max_parallel):
+        """Raise too_many_runs now, before a refused run changes any session state.
+
+        `start()` checks again under the same lock, so a run that slips in
+        between is still refused there.
+        """
+        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):
         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]
+            if max_parallel:
+                # Counted under the lock and without this run's own record, which a
+                # 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)
+            if label:
+                record["label"] = label
             data["runs"].insert(0, record)
             _prune_finished_runs(data)
             _write_registry(self.path, data)
@@ -341,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
@@ -358,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))]
@@ -384,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/run_usage.py

@@ -14,6 +14,11 @@ The definitions below are therefore normative, not a suggestion:
                         natively; Codex does not, so its cache-inclusive count
                         is reduced here rather than left for a reader to guess.
   cache_creation_tokens Tokens written to the provider's prompt cache.
+  cache_creation_1h_tokens
+                        The part of cache_creation_tokens written with
+                        Anthropic's one-hour TTL, which costs 2x instead of
+                        1.25x. A subset, never added to a total; absent when
+                        the provider does not report the split.
   cache_read_tokens     Tokens served from it.
   cached_input_tokens   cache_creation + cache_read. Kept because it is a
                         published field of `cdx run --json`, and because the
@@ -31,8 +36,8 @@ The definitions below are therefore normative, not a suggestion:
                         quantity.
 
 Cache creation and cache read are separate fields because they cost very
-differently -- 1.25x and 0.1x of uncached input -- and a weighted figure cannot
-recover the split once they are summed.
+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
@@ -49,6 +54,7 @@ USAGE_KEYS = (
     "input_tokens",
     "cached_input_tokens",
     "cache_creation_tokens",
+    "cache_creation_1h_tokens",
     "cache_read_tokens",
     "output_tokens",
     "reasoning_tokens",
@@ -64,7 +70,7 @@ def empty_usage():
 
 
 def normalize_usage(input_tokens=None, cache_creation_tokens=None, cache_read_tokens=None,
-                    output_tokens=None, reasoning_tokens=None):
+                    output_tokens=None, reasoning_tokens=None, cache_creation_1h_tokens=None):
     """Build a usage record from the four measured quantities.
 
     The derived fields are computed here and only here. A record whose parts are
@@ -80,6 +86,11 @@ def normalize_usage(input_tokens=None, cache_creation_tokens=None, cache_read_to
     }
     if all(value is None for value in parts.values()):
         return empty_usage()
+    long_ttl = _non_negative(cache_creation_1h_tokens)
+    if long_ttl is not None:
+        # A subset of the writes; more than the writes is not a subset.
+        long_ttl = min(long_ttl, parts["cache_creation_tokens"] or 0)
+    parts["cache_creation_1h_tokens"] = long_ttl
     cached = _sum_present(parts["cache_creation_tokens"], parts["cache_read_tokens"])
     total = _sum_present(
         parts["input_tokens"],
@@ -94,12 +105,13 @@ def normalize_usage(input_tokens=None, cache_creation_tokens=None, cache_read_to
 #:
 #: Defaults for rows without an explicit cache-read price. Newer models can
 #: discount reads further; both stats and currency use the table's rate.
-#: Anthropic's one-hour cache TTL costs 2x instead; nothing in a transcript
-#: says which TTL was used, so long-TTL writes are under-weighted. Cache writes
-#: are a small share of a cache-heavy session, so that error is bounded --
-#: stated here rather than hidden behind a single averaged number.
+#: Anthropic's one-hour cache TTL costs 2x instead. Claude transcripts report
+#: that split as `cache_creation.ephemeral_1h_input_tokens`; Claude Code writes
+#: most of its cache that way, so pricing every write at 1.25x understated
+#: them by up to 1.6x. A record without the split keeps the 1.25x rate.
 CACHE_READ_MULTIPLIER = 0.1
 CACHE_WRITE_MULTIPLIER = 1.25
+CACHE_WRITE_1H_MULTIPLIER = 2.0
 
 #: What an output token costs relative to an uncached input one, when the model
 #: is unknown. Current model ratios vary, so an unknown model is priced at the
@@ -144,7 +156,8 @@ def weighted_usage(usage, model=None, prices=None):
     That is not the ranking anyone reading `cdx stats` is looking for.
 
     Output and cache-read ratios come from the model that served the run.
-    Cache writes retain the five-minute TTL assumption.
+    Cache writes use the one-hour rate for the part the provider reported as
+    one-hour, the five-minute rate for the rest.
 
     `reasoning_tokens` is deliberately excluded: Codex reports it as a subset
     of its output, and counting it would bill those tokens twice.
@@ -154,12 +167,13 @@ def weighted_usage(usage, model=None, prices=None):
     weights = {
         "input_tokens": 1.0,
         "cache_creation_tokens": CACHE_WRITE_MULTIPLIER,
+        "cache_creation_1h_tokens": CACHE_WRITE_1H_MULTIPLIER - CACHE_WRITE_MULTIPLIER,
         "cache_read_tokens": cache_read_multiplier(model, prices),
         "output_tokens": output_multiplier(model, prices),
     }
     present = []
     for key, weight in weights.items():
-        value = usage.get(key)
+        value = _long_ttl_writes(usage) if key == "cache_creation_1h_tokens" else usage.get(key)
         if value is not None:
             if weight is None and value:
                 return None
@@ -297,9 +311,20 @@ def estimate_cost(usage, model, prices=None):
     ]
     if not present:
         return None
+    long_ttl = _long_ttl_writes(usage) or 0
+    present.append(rate["input"] * (CACHE_WRITE_1H_MULTIPLIER - CACHE_WRITE_MULTIPLIER) * long_ttl)
     return sum(present) / 1_000_000
 
 
+def _long_ttl_writes(usage):
+    """One-hour cache writes, bounded by the writes they are a part of."""
+    long_ttl = usage.get("cache_creation_1h_tokens")
+    if not isinstance(long_ttl, (int, float)) or isinstance(long_ttl, bool) or long_ttl <= 0:
+        return None
+    writes = usage.get("cache_creation_tokens")
+    return min(long_ttl, writes) if isinstance(writes, (int, float)) and not isinstance(writes, bool) else None
+
+
 def claude_usage_dedup_key(record):
     """What identifies one *billed* Claude API response in a transcript.
 
@@ -362,6 +387,7 @@ def coerce_usage(usage):
         cache_read_tokens=usage.get("cache_read_tokens"),
         output_tokens=usage.get("output_tokens"),
         reasoning_tokens=usage.get("reasoning_tokens"),
+        cache_creation_1h_tokens=usage.get("cache_creation_1h_tokens"),
     )
     if record["cached_input_tokens"] is None:
         # A legacy record carrying only the fused figure: keep it visible rather
@@ -493,6 +519,7 @@ def _usage_from_dict(value):
     return normalize_usage(
         input_tokens=input_tokens,
         cache_creation_tokens=cache_creation,
+        cache_creation_1h_tokens=_nested_int(usage, "cache_creation", "ephemeral_1h_input_tokens"),
         cache_read_tokens=cache_read,
         output_tokens=_int_value(usage.get("output_tokens"), usage.get("completion_tokens")),
         reasoning_tokens=_int_value(