cdx-manager 0.20.13 → 0.21.0

package/docs/technical-overview.md

@@ -0,0 +1,92 @@
+# Technical reference
+
+## Technical Overview
+
+- Python 3.9+.
+- Environment isolation per session:
+  - Codex sessions override `CODEX_HOME` to a dedicated profile directory.
+  - Claude sessions override `HOME` to a dedicated profile directory and disable Claude Code commit co-author attribution by default.
+  - On macOS, Claude credentials use a profile-specific keychain entry. Quota refresh reads that entry before legacy credential files; `cdx cp` and `cdx ren` transfer only the profile's entry, never the system keychain directory. Rename refuses existing destination entries and reports any old-entry cleanup failure after the new session becomes usable; `cdx rm` deletes the profile's entry with the profile.
+  - Antigravity sessions launch `agy` with a dedicated `HOME` for file-based settings; Google account credentials may still be stored in the OS keyring by Antigravity itself.
+  - Ollama sessions use the local Ollama server and launch `ollama run <model>`; set a model with `cdx set <name> --model <model>`.
+  - New Codex sessions seed their auth home from your existing global `~/.codex/auth.json` when available, so an already logged-in Codex CLI can be reused without giving up per-session isolation afterward.
+- Persistence:
+  - Session registry at `~/.cdx/sessions.json` (versioned JSON store).
+  - Per-session state at `~/.cdx/state/<name>.json`.
+  - Per-workspace shared context at `~/.cdx/contexts/<workspace-hash>/context.md`.
+  - Auth and provider data under `~/.cdx/profiles/<name>/`.
+  - All paths are URL-encoded to support arbitrary session names.
+- Status resolution pipeline:
+  - Primary source: recorded status fields on the session record.
+  - Codex live source: `codex app-server` JSON-RPC `account/rateLimits/read`, normalized into 5-hour, weekly, reset, credit, and plan fields.
+  - Fallback: `status-source` scans provider JSONL history files and terminal log transcripts, strips ANSI/OSC sequences, and extracts `usage%`, `5h remaining%`, and `week remaining%` via pattern matching.
+- Status latency controls: use `cdx status --cached` to skip live probes, `cdx status --timeout SECONDS` for one command, or `CDX_STATUS_TIMEOUT_SECONDS` to lower the default Codex live-probe timeout.
+- Claude status refreshes are cached briefly by default; pass `--refresh` to force a live rate-limit probe.
+- On Linux, transcript capture uses the `util-linux` `script -c` command form.
+- If `script` is unavailable, Codex launch falls back to running without transcript capture.
+- On Windows, transcript capture is optional. If no compatible `script` wrapper is installed, Codex still launches normally without transcript capture.
+- Auth probe: synchronous subprocess call to `codex login status` or `claude auth status` before any interactive launch.
+- Signal forwarding: `SIGINT`, `SIGTERM`, and `SIGHUP` are forwarded to the child process and produce clean exit codes.
+- Test stack: `pytest`, `pytest-cov`, and `ruff` via the documented `dev` dependency extra.
+
+## Project Structure
+
+```text
+bin/
+  cdx.js                # Node launcher used by npm
+  python-runner.js      # Shared Python resolver and process wrapper
+  cdx                   # Python entrypoint invoked by the launcher
+
+src/
+  cli.py                # Top-level command router
+  cli_commands.py       # Command handlers and argument handling
+  cli_render.py         # Terminal formatting, tables, colors, and errors
+  backup_bundle.py      # Portable session bundle encoding/decoding + auth encryption
+  status_view.py        # Status table/detail rendering and priority ranking
+  provider_runtime.py   # Provider launch/auth commands, transcripts, signals
+  claude_refresh.py     # Claude usage refresh orchestration
+  session_service.py    # Session lifecycle: create, copy, rename, launch, remove, status
+                        # resolution, auth state management
+  session_store.py      # JSON persistence layer: sessions.json + per-session
+                        # state files
+  status_source.py      # Status artifact discovery: scans JSONL history files
+                        # and terminal log transcripts, strips ANSI sequences,
+                        # extracts usage metrics via pattern matching
+  config.py             # CDX_HOME resolution (env override or ~/.cdx)
+  errors.py             # CdxError with optional exit code
+  __init__.py           # Public Python exports
+
+test/
+  test_cli_py.py            # CLI command dispatch tests
+  test_session_service_py.py  # Session service unit tests
+```
+
+## Data Layout
+
+All session data lives under `CDX_HOME` (default: `~/.cdx/`):
+
+```text
+~/.cdx/
+  sessions.json             # Session registry (versioned, all sessions)
+  state/
+    <encoded-name>.json     # Per-session rehydration state
+    launch_history.jsonl    # Append-only launch history
+  contexts/
+    <workspace-hash>/context.md     # Current-workspace shared context / memory
+    global/context.md               # Global cdx memory
+    projects/<encoded-name>/context.md  # Named project memory from cdx memory --project NAME
+  profiles/
+    <encoded-name>/         # Codex session: CODEX_HOME points here
+      log/
+        cdx-session.log     # Terminal transcript (written by script(1))
+    <encoded-name>/
+      claude-home/          # Claude session: HOME points here
+        log/
+          cdx-session.log
+```
+
+Session names are URL-encoded when used as directory or file names. CLI command names such as `add`, `disk`, `status`, and `login` are reserved and cannot be used as new session names.
+
+`cdx memory` is the user-facing interface for explicit memory. `--project NAME` uses a stable free-form project name; `--project /path/to/repo` resolves to the same workspace-hash memory that repo would use as the current workspace. `append` adds the text as-is with a clean newline boundary; it does not add dates or headings. `list` reports global memory, named project memories, and the current workspace memory when present; it does not scan your filesystem for repos.
+
+Provider-private memory files, such as Codex SQLite memory databases or Claude Code project memory files, are not edited by `cdx memory`.

package/docs/tray-local-testing.md

@@ -0,0 +1,154 @@
+# Testing tray changes locally
+
+How to see a tray change working on a development machine, from the cheapest
+loop to the one that puts a real icon in the menu bar. Every command here was
+run on macOS (Apple Silicon); the notes say where another platform differs.
+
+The ordering is the point: three of the four loops need no install, no signing,
+and no interference with the companion already running. Reach for the last one
+only when the change is something only a drawn menu can show.
+
+## Prerequisite
+
+A Rust toolchain, once:
+
+```bash
+rustup default stable        # nothing below builds without this
+```
+
+`cargo` alone is not enough — `rustup` with no default toolchain fails with
+"could not choose a version of cargo to run", which reads like a broken install
+and is not one.
+
+Python needs nothing: the repository runs from `./bin/cdx`.
+
+## 1. CDX side only — no Rust at all
+
+Anything that changes what CDX publishes (the snapshot, `cdx tray …` commands,
+the alert payload) is testable without building the companion:
+
+```bash
+./bin/cdx tray status --json | head -40      # the whole snapshot contract
+./bin/cdx tray terminal                      # one preference, read back
+python3 -m pytest test/test_tray_*.py test/test_notify_py.py -q
+```
+
+`./bin/cdx` is the working tree, not the installed CDX. Use it deliberately:
+`cdx` on the PATH is the released build and will not show your change.
+
+## 2. The menu, rendered to stdout
+
+The companion draws its whole menu to the terminal with `--print`, which is the
+loop to live in. First build is around 25 seconds, every one after is instant.
+
+```bash
+CDX_TRAY_CDX="$PWD/bin/cdx" cargo run -q --manifest-path tray/Cargo.toml -- --print
+```
+
+`CDX_TRAY_CDX` is what points the companion at the working tree instead of the
+installed CDX. Without it you are testing the released behaviour with a
+development menu, which looks like it works and proves nothing.
+
+Submenus are rendered indented, checks as `(•)`, disabled actions as `[ ]`, so
+the output covers everything a drawn menu shows.
+
+Safe to run while the real companion is running: `--print` reads the spool but
+neither heartbeats nor acknowledges, so it cannot steal an alert from the tray
+that is actually delivering them.
+
+## 3. The test suites
+
+```bash
+cargo test -q --manifest-path tray/Cargo.toml       # 89 tests, well under a second
+python3 -m pytest test/ -q
+```
+
+The Rust suite covers the menu, the snapshot reader, the spool and the unread
+badge — everything except the platform backends, which have no headless test and
+are the reason loop 4 exists.
+
+## 4. A real icon in the menu bar
+
+Only for what the first three cannot show: the drawn cell, the notification
+banner, the click paths, the icon itself.
+
+```bash
+./scripts/build-tray.sh --dev        # writes tray/target/release/CDX.app
+```
+
+The companion is single-instance — a pid lock in `TMPDIR` — so the development
+build will not start while the installed one holds it. Quit the installed
+companion from its own menu first, then:
+
+```bash
+CDX_TRAY_CDX="$PWD/bin/cdx" open -n tray/target/release/CDX.app
+```
+
+To go back to the installed companion afterwards:
+
+```bash
+cdx tray launch                      # stops whatever is running, starts the installed one
+cdx tray doctor                      # confirms which one is running, and against which CDX
+```
+
+For the repeatable local cycle, use the checkout helper instead. It builds and
+verifies the development bundle, then restores the recorded installed companion
+without replacing it:
+
+```bash
+./scripts/tray-dev.sh load
+./scripts/tray-dev.sh unload
+```
+
+See `logics/runbook/run_003_load_and_unload_the_local_macos_tray_companion.md`
+for prerequisites, verification, and rollback.
+
+`--dev` is signed ad-hoc, so **its identity changes at every rebuild**. Two
+consequences: macOS forgets the notification authorization each time, and the
+banner loses the app's own icon. Anything about notification *appearance* has to
+be tested with a real signed build (`CDX_TRAY_SIGN_IDENTITY=… ./scripts/build-tray.sh`).
+`--dev` refuses `--package` outright, and nothing built this way should ever be
+distributed. See `adr_005`.
+
+## Firing an alert without waiting for an agent
+
+The whole notification chain — hook, privacy filter, spool, companion, banner —
+in one command:
+
+```bash
+echo '{"hook_event_name":"Stop","cwd":"'"$PWD"'","last_assistant_message":"Smoke test."}' \
+  | CDX_SESSION_NAME=runbook CDX_NOTIFY_PREVIEW=1 ./bin/cdx notify
+tail -1 "${CDX_HOME:-$HOME/.cdx}/tray/events.jsonl"      # what the companion was handed
+```
+
+Swap `hook_event_name` for `StopFailure` (add `"error_type"`, `"error_message"`)
+or `PermissionRequest` (add `"tool_name"`, `"tool_input"`) to exercise the other
+two alert shapes. Drop `CDX_NOTIFY_PREVIEW=1` to see what a session without
+response previews shows.
+
+This writes a real line to the spool and raises a real banner. Harmless, but it
+is not a dry run.
+
+## Testing against a store that is not yours
+
+To exercise the menu without touching real sessions:
+
+```bash
+export CDX_HOME=/tmp/cdx-dev
+./bin/cdx tray status --json                 # empty store: icon "unknown", reason "no_sessions"
+cp ~/.cdx/sessions.json "$CDX_HOME/"         # or copy real rows in for a realistic menu
+```
+
+`CDX_HOME` is read by every CDX path, including `cdx notify`, so the isolated
+store gets its own spool and its own preferences.
+
+## Checking what is actually installed
+
+```bash
+cdx tray doctor
+```
+
+It names the installed companion, whether it is running and under which pid,
+which `cdx` binary that companion calls, and whether the hook store the
+notification path writes to is the one the companion reads. A tray that receives
+no alert while everything looks fine is almost always a `hook_store` mismatch.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "cdx-manager",
-  "version": "0.20.13",
+  "version": "0.21.0",
   "description": "Terminal session manager for Codex and Claude accounts.",
   "license": "MIT",
   "author": "Alexandre Agostini",
@@ -30,6 +30,7 @@
     "!bin/**/*.pyc",
     "checksums",
     "changelogs",
+    "docs",
     "src",
     "!src/**/__pycache__",
     "!src/**/*.pyc",

package/pyproject.toml

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

package/src/cli.py

@@ -260,7 +260,7 @@ def _print_help(use_color=False):
         f"  {_style('cdx resume <name> [--json]', '36', use_color)}",
         f"  {_style('cdx can-resume <name> [--json]', '36', use_color)}",
         f"  {_style('cdx handoff <name> [--json]', '36', use_color)}",
-        f"  {_style('cdx handoff <source> <target> [--source-conversation ID | --source-transcript PATH] [--json]', '36', use_color)}",
+        f"  {_style('cdx handoff <source> <target> [--source-conversation ID | --source-native-transcript PATH | --source-transcript PATH] [--json]', '36', use_color)}",
         f"  {_style('cdx add [provider] <name> [--model MODEL] [--json]', '36', use_color)}",
         f"  {_style('cdx cp <source> <dest> [--json]', '36', use_color)}",
         f"  {_style('cdx ren <source> <dest> [--json]', '36', use_color)}",

package/src/cli_args.py

@@ -30,7 +30,7 @@ EXPORT_USAGE = "Usage: cdx export <file> [--include-auth] [--force] [--json] [--
 IMPORT_USAGE = "Usage: cdx import <file> [--force|--merge] [--allow-authless-force] [--json] [--sessions name1,name2] [--passphrase-env VAR|--passphrase-stdin]"
 CONTEXT_USAGE = "Usage: cdx context show|path|init|edit|clear|set|append [text...] [--json]"
 MEMORY_USAGE = "Usage: cdx memory [--global|--project NAME_OR_PATH] [show|view|path|init|edit|clear|set|append|list] [text...] [--json]"
-HANDOFF_USAGE = "Usage: cdx handoff <name> [--json] | cdx handoff <source> <target> [--source-conversation ID | --source-transcript PATH] [--json]"
+HANDOFF_USAGE = "Usage: cdx handoff <name> [--json] | cdx handoff <source> <target> [--source-conversation ID | --source-native-transcript PATH | --source-transcript PATH] [--json]"
 LABEL_USAGE = "Usage: cdx label <name> <label> [--json] | cdx label <name> --clear [--json]"
 SET_USAGE = "Usage: cdx set <name>|--sessions all|a,b|--provider PROVIDER [--power minimal|low|medium|high|xhigh] [--permission review|default|auto|full] [--fast on|off] [--rtk on|off] [--logics on|off] [--model MODEL] [--fallback-model MODEL[,MODEL...]] [--budget USD] [--extra-args 'ARGS'] [--priority 0..100] [--json]"
 UNSET_USAGE = "Usage: cdx unset <name>|--sessions all|a,b|--provider PROVIDER (--power|--reasoning-effort|--permission|--fast|--rtk|--logics|--model|--fallback-model|--budget|--extra-args|--priority|--all) [--json]"

package/src/commands/launch.py

@@ -191,6 +191,8 @@ def handle_launch(command, ctx, initial_prompt=None, resume=False, force_json=No
     if force_json is not None:
         json_flag = force_json
     warnings = _update_notice_warnings(ctx)
+    active_runtime = ctx["service"].get("active_session_runtime")
+    overlap_at_start = bool(active_runtime and active_runtime(command))
     _warn_if_session_already_running(command, ctx)
     session = ctx["service"]["get_session"](command)
     if not session:
@@ -258,6 +260,18 @@ def handle_launch(command, ctx, initial_prompt=None, resume=False, force_json=No
                 {"status": "stopped", "returncode": info.get("returncode")},
             )
 
+    # A resumed transcript may grow outside CDX between launches. Capture its
+    # cumulative value immediately before starting the provider.
+    baseline, baseline_path, baseline_match, _ = extract_interactive_usage(
+        session.get("provider"), _get_auth_home(session), None, _conversation_id(session),
+    )
+    if baseline_match != "conversation_id":
+        baseline = baseline_path = None
+    def overlap_reason():
+        current = active_runtime(session["name"]) if active_runtime else None
+        if overlap_at_start or (runtime_run_id and current and current.get("runId") != runtime_run_id):
+            return "overlapping_session"
+        return None
     try:
         run_info = _run_interactive_provider_command(
             session, "resume" if resume else "launch", spawn=ctx.get("spawn"), cwd=cwd, env_override=ctx.get("env"),
@@ -270,7 +284,9 @@ def handle_launch(command, ctx, initial_prompt=None, resume=False, force_json=No
     except CdxError as error:
         run_info = getattr(error, "run_info", {}) or {}
         run_info = _attach_interactive_usage(
-            session, run_info, ctx["service"]["get_launch_history"](session["name"], limit=50)
+            session, run_info, ctx["service"]["get_launch_history"](session["name"], limit=None),
+            baseline=(baseline_path, baseline),
+            uncertain_reason=overlap_reason(),
         )
         if not json_flag and error.exit_code in INTERRUPT_EXIT_CODES:
             ctx["out"](f"{_goodbye_line(session, run_info, ctx['use_color'])}\n")
@@ -290,7 +306,9 @@ def handle_launch(command, ctx, initial_prompt=None, resume=False, force_json=No
             })
         raise
     success_run_info = _attach_interactive_usage(
-        session, run_info, ctx["service"]["get_launch_history"](session["name"], limit=50)
+        session, run_info, ctx["service"]["get_launch_history"](session["name"], limit=None),
+        baseline=(baseline_path, baseline),
+        uncertain_reason=overlap_reason(),
     )
     ctx["service"]["record_launch_history"](session["name"], {
         "status": "success",
@@ -332,7 +350,7 @@ def _goodbye_line(session, run_info, use_color):
     return _dim(" · ".join(parts), use_color)
 
 
-def _attach_interactive_usage(session, run_info, history=None):
+def _attach_interactive_usage(session, run_info, history=None, baseline=None, uncertain_reason=None):
     """Attach this run's own token usage without affecting launch outcome.
 
     Both interactive readers report a cumulative figure, so what a run *stores*
@@ -369,7 +387,19 @@ def _attach_interactive_usage(session, run_info, history=None):
         # `model` is optional and usually unset, because the session takes the
         # provider's default.
         run_info["usage_model"] = model
-    previous = _previous_cumulative(history, provider_transcript)
+    if uncertain_reason:
+        run_info["usage_attribution"] = uncertain_reason
+        return run_info
+    baseline_path, baseline_usage = baseline or (None, None)
+    if baseline_usage is not None and baseline_path == provider_transcript:
+        previous = baseline_usage
+        run_info["usage_attribution"] = "launch_boundary"
+    elif baseline is not None:
+        previous = None
+        run_info["usage_attribution"] = "new_transcript" if not transcript_predates_run(
+            provider_transcript, started_at) else "uncertain_transcript"
+    else:
+        previous = _previous_cumulative(history, provider_transcript)
     if previous is not None:
         delta = usage_delta(cumulative, previous)
         if delta is not None:
@@ -402,7 +432,7 @@ def _parse_handoff_args(rest):
         arg = args[index]
         if arg.startswith("--"):
             key, sep, value = arg.partition("=")
-            if key not in ("--source-conversation", "--source-transcript") or key in flags:
+            if key not in ("--source-conversation", "--source-transcript", "--source-native-transcript") or key in flags:
                 raise CdxError(HANDOFF_USAGE)
             if not sep:
                 index += 1
@@ -420,14 +450,15 @@ def _parse_handoff_args(rest):
 
 def _handoff_source(source, workspace, flags, ctx, json_flag):
     try:
-        return resolve_source(source, workspace, flags.get("--source-conversation"), flags.get("--source-transcript"))
+        return resolve_source(source, workspace, flags.get("--source-conversation"),
+                              flags.get("--source-transcript"), flags.get("--source-native-transcript"))
     except HandoffSourceError as error:
         candidates = error.candidates
         # JSON and non-interactive callers always make an explicit second call.
         if json_flag or not ctx["stdin_is_tty"] or not candidates or flags:
             raise
         ctx["out"](str(error) + "\n" + "".join(
-            f"  {i + 1}. {c['conversation_id']} | {c['workspace']} | last event {c['last_event_at'] or 'unknown'}\n"
+            f"  {i + 1}. {c['conversation_id']} | {c['path']} | {c['workspace']} | last event {c['last_event_at'] or 'unknown'}\n"
             for i, c in enumerate(candidates)
         ))
         ask = ctx["options"].get("input") or input
@@ -439,7 +470,11 @@ def _handoff_source(source, workspace, flags, ctx, json_flag):
             raise CdxError("Handoff cancelled.", exit_code=130) from None
         if not answer.isdigit() or not 1 <= int(answer) <= len(candidates):
             raise CdxError("Handoff cancelled: choose a listed source.") from None
-        return resolve_source(source, workspace, candidates[int(answer) - 1]["conversation_id"])
+        chosen = candidates[int(answer) - 1]
+        exact = resolve_source(source, workspace, native_path=chosen["path"])
+        if (exact["sha256"], exact["extent_bytes"]) != (chosen["sha256"], chosen["extent_bytes"]):
+            raise HandoffSourceError("Selected native transcript changed during selection.") from None
+        return exact
 
 
 def handle_handoff(rest, ctx):
@@ -464,7 +499,7 @@ def handle_handoff(rest, ctx):
             transcript = _handoff_source(source, workspace, flags, ctx, json_flag)
         except HandoffSourceError as error:
             if not json_flag:
-                choices = "\n".join(f"  {c['conversation_id']} | {c['workspace']} | {c['last_event_at'] or 'unknown'}" for c in error.candidates)
+                choices = "\n".join(f"  {c['conversation_id']} | {c['path']} | {c['workspace']} | {c['last_event_at'] or 'unknown'}" for c in error.candidates)
                 raise CdxError(str(error) + ("\nCandidates:\n" + choices if choices else "")) from error
             _write_json(ctx, _json_failure("handoff", "handoff_source_unresolved", str(error), candidates=error.candidates))
             return error.exit_code

package/src/commands/runs.py

@@ -44,7 +44,7 @@ from ..provider_runtime import (
 from ..run_command import read_run_prompt, run_cdx_error_code, run_launch_payload, run_result_payload
 from ..run_failover import MAX_FAILOVER_TRANSITIONS, failover_reason
 from ..run_registry import RunRegistry, build_code_review_report
-from ..run_usage import extract_run_usage
+from ..run_usage import extract_run_observation
 from ..session_ranking import FACTOR_DESCRIPTIONS, rank_sessions, selection_policy
 from ..status_view import _now_timestamp, _priority_reset_timestamp
 
@@ -390,10 +390,20 @@ def _reconcile_background_runs(ctx):
                 status=status,
                 final_payload={
                     "usage": outcome["usage"],
+                    "usage_model": outcome["usage_model"],
                     "result": outcome["result"],
                     "background_path": BACKGROUND_PATH_PROVIDER,
                 },
             )
+            ctx["service"]["record_launch_history"](session["name"], {
+                "status": "success" if status == "succeeded" else "failed",
+                "action": "run",
+                "run_id": run["run_id"],
+                "attempt": 1,
+                "cwd": run.get("cwd"),
+                "usage": outcome["usage"],
+                "usage_model": outcome["usage_model"],
+            })
         except Exception:
             continue
 
@@ -645,8 +655,19 @@ def handle_run(rest, ctx):
                 spawn=ctx.get("spawn_headless") or ctx.get("spawn"),
                 run_id=run_id,
             )
-            usage = extract_run_usage(run_session.get("provider"), run_info.get("stdout_path"))
-            run_info = {**run_info, "usage": usage}
+            usage, usage_model = extract_run_observation(
+                run_session.get("provider"), run_info.get("stdout_path"),
+            )
+            run_info = {**run_info, "usage": usage, "usage_model": usage_model}
+            ctx["service"]["record_launch_history"](run_session["name"], {
+                "status": "success" if run_info.get("returncode") == 0 else "failed",
+                "action": "run",
+                "run_id": run_id,
+                "attempt": len(attempted),
+                "cwd": cwd,
+                "exit_code": run_info.get("returncode"),
+                **run_info,
+            })
             if run_info.get("returncode") == 0 or not parsed.get("failover"):
                 break
             reason = failover_reason(
@@ -714,12 +735,6 @@ def handle_run(rest, ctx):
                 run_info=run_info,
                 task_report=task_report,
             )
-            ctx["service"]["record_launch_history"](session["name"], {
-                "status": "success",
-                "cwd": cwd,
-                "exit_code": 0,
-                **run_info,
-            })
             _write_json(ctx, final_payload)
             return 0
         if failover_error_code == "failover_exhausted":
@@ -754,18 +769,25 @@ def handle_run(rest, ctx):
             error=final_payload.get("error"),
             task_report=build_code_review_report(run_id, final_payload) if parsed.get("kind") == "code-review" else None,
         )
-        ctx["service"]["record_launch_history"](session["name"], {
-            "status": "failed",
-            "cwd": cwd,
-            "error": str(error),
-            "exit_code": error.exit_code,
-            **run_info,
-        })
         _write_json(ctx, final_payload)
         return error.exit_code or 1
     except CdxError as error:
         run_info = getattr(error, "run_info", None)
         cancelled = bool(getattr(error, "cancelled", False))
+        if run_info and run_id:
+            usage, usage_model = extract_run_observation(
+                run_session.get("provider"), run_info.get("stdout_path"),
+            )
+            run_info = {**run_info, "usage": usage, "usage_model": usage_model}
+            ctx["service"]["record_launch_history"](run_session["name"], {
+                "status": "failed",
+                "action": "run",
+                "run_id": run_id,
+                "attempt": len(attempted) if "attempted" in locals() else 1,
+                "cwd": cwd,
+                "exit_code": error.exit_code,
+                **run_info,
+            })
         final_payload = run_result_payload(
             API_SCHEMA_VERSION,
             False,

package/src/commands/status.py

@@ -276,6 +276,8 @@ def _summarize_stats(entries):
             "usage_runs": 0,
             "cost_usd": 0.0,
             "weighted_tokens": 0,
+            "weighted_runs": 0,
+            "unweighted_runs": 0,
             "priced_runs": 0,
             "unpriced_models": set(),
             "unvouched_runs": 0,
@@ -316,11 +318,14 @@ def _summarize_stats(entries):
             # model cdx never saw stays unpriced rather than being charged at a
             # default tier, and `priced_runs` says how much of the figure is
             # actually covered.
-            # Weighted per entry, not on the summed row: the output ratio is
-            # the one multiplier that differs between vendors, and a session's
-            # runs can span models.
-            row["weighted_tokens"] += weighted_usage(
-                entry.get("usage"), entry.get("usage_model")) or 0
+            # Weighted per entry, not on the summed row: output and cache-read
+            # ratios vary by model, and a session's runs can span models.
+            weighted = weighted_usage(entry.get("usage"), entry.get("usage_model"))
+            if weighted is None:
+                row["unweighted_runs"] += 1
+            else:
+                row["weighted_tokens"] += weighted
+                row["weighted_runs"] += 1
             cost = estimate_cost(entry.get("usage"), entry.get("usage_model"))
             if cost is not None:
                 row["cost_usd"] += cost
@@ -356,37 +361,6 @@ def _summarize_stats(entries):
             output_tokens=row["output_tokens"],
         )
         row["total_tokens"] = derived["total_tokens"] or 0
-        if not row["weighted_tokens"]:
-            # Records written before the model was recorded: weigh the row as a
-            # whole, at the default ratio, rather than reporting nothing.
-            row["weighted_tokens"] = weighted_usage(derived) or 0
-        row["unpriced_models"] = sorted(row["unpriced_models"])
-    for row in rows.values():
-        # Derive from the summed parts rather than summing each run's stored
-        # total. Records written before the definition was settled carry a
-        # total that excluded cache, and adding those to correct ones produced
-        # a row that contradicted itself -- CACHE in the hundreds of millions
-        # beside a TOTAL in the low millions.
-        #
-        # Those records also lack the creation/read split, so the fused
-        # `cached_input_tokens` is the one field both eras share. Where the
-        # split is missing it is read as cache read: that is what the
-        # 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.
-        split = row["cache_creation_tokens"] + row["cache_read_tokens"]
-        legacy_cache = max(0, row["cached_input_tokens"] - split)
-        derived = normalize_usage(
-            input_tokens=row["input_tokens"],
-            cache_creation_tokens=row["cache_creation_tokens"],
-            cache_read_tokens=row["cache_read_tokens"] + legacy_cache,
-            output_tokens=row["output_tokens"],
-        )
-        row["total_tokens"] = derived["total_tokens"] or 0
-        if not row["weighted_tokens"]:
-            # Records written before the model was recorded: weigh the row as a
-            # whole, at the default ratio, rather than reporting nothing.
-            row["weighted_tokens"] = weighted_usage(derived) or 0
         row["unpriced_models"] = sorted(row["unpriced_models"])
     return sorted(
         rows.values(),
@@ -408,6 +382,8 @@ def _stats_totals(rows):
         "usage_runs": sum(row["usage_runs"] for row in rows),
         **{key: sum(row[key] for row in rows) for key in 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),
         "cost_usd": sum(row["cost_usd"] for row in rows),
         "priced_runs": sum(row["priced_runs"] for row in rows),
         "unpriced_models": sorted({m for row in rows for m in row["unpriced_models"]}),
@@ -518,7 +494,8 @@ def _format_stats(rows, totals, period=None, use_color=False, active_sessions=No
             _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(_format_token_count(row["weighted_tokens"]), "1;95" if row["weighted_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 "-",
                    "1;33" if row["priced_runs"] else "2", use_color),
             _style(_format_duration_ms(row["duration_ms"]), "33" if row["duration_ms"] else "2", use_color),
@@ -535,7 +512,9 @@ def _format_stats(rows, totals, period=None, use_color=False, active_sessions=No
             "Totals: "
             f"{totals['launches']} runs, {totals['usage_runs']} with usage, "
             f"{_format_token_count(totals['total_tokens'])} tokens "
-            f"({_format_token_count(totals['weighted_tokens'])} cost-equivalent"
+            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 "")
             + (f", {_format_usd(totals['cost_usd'])} at list on {totals['priced_runs']} priced run"
                f"{'s' if totals['priced_runs'] != 1 else ''} [{token_prices()[1]}]"
                if totals["priced_runs"] else ", no run priced")
@@ -631,6 +610,13 @@ def handle_stats(rest, ctx):
             period=_public_history_period(parsed["period"]),
             stats=rows,
             totals=totals,
+            accounting={
+                "launches_unit": "history_attempts",
+                "period_policy": "whole_run_overlap",
+                "weighted_coverage": "weighted_runs/usage_runs",
+                "price_coverage": "priced_runs/usage_runs",
+                "price_basis": token_prices()[1],
+            },
         ))
         return 0
     active_sessions = _active_session_names(ctx)

package/src/context_store.py

@@ -8,6 +8,7 @@ from urllib.parse import quote, unquote
 
 from .errors import CdxError
 from .fs_utils import atomic_write
+from .run_registry import _registry_lock
 from .session_store import _ensure_dir
 
 DEFAULT_CONTEXT_TEMPLATE = """# Shared Context
@@ -127,7 +128,7 @@ def append_context_path(path, note):
     note = str(note or "").strip()
     if not note:
         raise CdxError("Memory append requires text.")
-    with _append_lock(path):
+    with _append_lock(path), _registry_lock(path, timeout_seconds=10, label="memory"):
         current = read_context_path(path).rstrip()
         content = f"{current}\n{note}" if current else note
         return write_context_path(path, content)