cdx-manager 0.20.14 → 0.21.0

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.14",
+  "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.14"
+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,
@@ -318,8 +320,12 @@ def _summarize_stats(entries):
             # actually covered.
             # Weighted per entry, not on the summed row: output and cache-read
             # ratios vary by model, and a session's runs can span models.
-            row["weighted_tokens"] += weighted_usage(
-                entry.get("usage"), entry.get("usage_model")) or 0
+            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
@@ -355,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(),
@@ -407,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"]}),
@@ -517,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),
@@ -534,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")
@@ -630,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)

package/src/handoff.py

@@ -11,7 +11,6 @@ from uuid import uuid4
 from .context_store import get_context_path, read_context
 from .errors import CdxError
 from .fs_utils import atomic_write
-from .interactive_usage import conversation_transcript
 from .provider_runtime import _get_auth_home, _list_launch_transcript_paths
 
 CANDIDATE_LIMIT = 20
@@ -25,13 +24,19 @@ class HandoffSourceError(CdxError):
 
 def _native_paths(session):
     home = _get_auth_home(session)
+    root = os.path.realpath(home)
+    def owned(path):
+        try:
+            return os.path.commonpath((root, os.path.realpath(path))) == root
+        except ValueError:
+            return False
     if session['provider'] == 'codex':
-        paths = glob.glob(os.path.join(home, 'sessions', '**', '*.jsonl'), recursive=True)
-        return [p for p in paths if 'subagents' not in os.path.relpath(p, home).split(os.sep)]
+        paths = glob.glob(os.path.join(glob.escape(home), 'sessions', '**', '*.jsonl'), recursive=True)
+        return [p for p in paths if owned(p) and 'subagents' not in os.path.relpath(p, home).split(os.sep)]
     if session['provider'] == 'claude':
         return sorted(set(
-            p for root in (('.claude', 'projects'), ('projects',))
-            for p in glob.glob(os.path.join(home, *root, '*', '*.jsonl'))
+            p for layout in (('.claude', 'projects'), ('projects',))
+            for p in glob.glob(os.path.join(glob.escape(home), *layout, '*', '*.jsonl')) if owned(p)
         ))
     return []
 
@@ -119,7 +124,7 @@ def source_candidates(session, workspace):
     return sorted(candidates, key=lambda c: (c['last_event_at'] or '', c['path']), reverse=True)[:CANDIDATE_LIMIT]
 
 
-def resolve_source(session, workspace, conversation_id=None, terminal_path=None):
+def resolve_source(session, workspace, conversation_id=None, terminal_path=None, native_path=None):
     workspace = os.path.realpath(workspace)
     if terminal_path:
         path = os.path.realpath(terminal_path)
@@ -150,26 +155,37 @@ def resolve_source(session, workspace, conversation_id=None, terminal_path=None)
     reason = 'No recorded conversation identity.'
     if session['provider'] not in ('codex', 'claude'):
         raise HandoffSourceError('No supported native transcript for this provider. Select a known launch log with --source-transcript PATH for degraded recovery.')
+    paths = _native_paths(session)
+    if native_path:
+        path = os.path.realpath(native_path)
+        allowed = {os.path.realpath(p) for p in paths}
+        if path not in allowed:
+            raise HandoffSourceError('Native transcript must be a top-level source file in the source profile.')
+        try:
+            info = inspect_transcript(path, session['provider'])
+        except CdxError as error:
+            raise HandoffSourceError(str(error)) from error
+        if info['workspace'] != workspace:
+            raise HandoffSourceError('Native transcript workspace does not match the target workspace.')
+        info['provenance'] = 'explicit_native_path'
+        return info
     if selected:
         if not isinstance(selected, str) or not re.fullmatch(r'[A-Za-z0-9_-]+', selected):
             raise HandoffSourceError('Invalid source conversation ID.')
-        path = conversation_transcript(session['provider'], _get_auth_home(session), selected)
-        # The native resolver may walk nested subagent directories; only top-level
-        # conversations are eligible for handoff, even when explicitly named.
-        paths = _native_paths(session)
-        if not path:
-            matches = [p for p in paths if os.path.basename(p) == selected + '.jsonl']
-            path = matches[0] if len(matches) == 1 else None
         reason = f'Conversation {selected} is missing or is not a top-level source.'
-        if path in paths:
+        matches = []
+        for path in paths:
             try:
                 info = inspect_transcript(path, session['provider'])
-                if info['conversation_id'] != selected or info['workspace'] != workspace:
-                    raise CdxError(f'Conversation identity or workspace mismatch: {selected}')
-                info['provenance'] = 'explicit_identity' if conversation_id else 'recorded_identity'
-                return info
-            except CdxError as error:
-                reason = str(error)
+            except CdxError:
+                continue
+            if info['conversation_id'] == selected and info['workspace'] == workspace:
+                matches.append(info)
+        if len(matches) > 1:
+            raise HandoffSourceError(f'Conversation {selected} has multiple native transcripts; select --source-native-transcript PATH.', matches)
+        if matches:
+            matches[0]['provenance'] = 'explicit_identity' if conversation_id else 'recorded_identity'
+            return matches[0]
     candidates = source_candidates(session, workspace)
     raise HandoffSourceError(
         reason + ' Select the intended ID with --source-conversation ID; no recency fallback is used.',