cdx-manager 0.21.6 → 0.22.0

package/src/cli_helpers.py

@@ -249,13 +249,23 @@ def _bootstrap_claude_setup_token(session, ctx):
     ctx["out"](
         "Minting a long-lived Claude setup-token for this session.\n"
     )
-    run_info = _run_interactive_provider_command(
-        session,
-        "setup-token",
-        spawn=ctx.get("spawn"),
-        env_override=ctx.get("env"),
-        signal_emitter=ctx.get("signal_emitter"),
-    )
+    try:
+        run_info = _run_interactive_provider_command(
+            session,
+            "setup-token",
+            spawn=ctx.get("spawn"),
+            env_override=ctx.get("env"),
+            signal_emitter=ctx.get("signal_emitter"),
+        )
+    except Exception as error:
+        # A failed or interrupted run can still have printed the token.
+        failed_path = (getattr(error, "run_info", None) or {}).get("transcript_path")
+        if failed_path:
+            try:
+                os.remove(failed_path)
+            except OSError:
+                pass
+        raise
     transcript_path = run_info.get("transcript_path")
     if not transcript_path or not os.path.isfile(transcript_path):
         raise CdxError(
@@ -304,11 +314,14 @@ def _format_launch_config(session, use_color=False):
         ("notify", "Agent alerts"),
         ("notify_preview", "Response preview"),
         ("scrub_env", "Scrub agent env"),
+        ("shared_memory", "Shared memory"),
+        ("retro", "Session retro"),
         ("model", "Model"),
         ("fallback_model", "Fallback"),
         ("budget", "Budget"),
         ("extra_args", "Extra args"),
         ("priority", "Priority"),
+        ("policy", "Policy"),
     ]:
         rows.append([
             _dim(label, use_color),
@@ -330,14 +343,14 @@ def _format_launch_settings_hint(name="<name>"):
     )
 
 def _format_launch_setting_value(launch, key, use_color=False):
-    if key in ("fast", "rtk", "logics", "notify", "notify_preview", "scrub_env"):
+    if key in ("fast", "rtk", "logics", "notify", "notify_preview", "scrub_env", "shared_memory", "retro"):
         if launch.get(key) is True:
             return _style("on", "32", use_color)
         if launch.get(key) is False:
             return _style("off", "2", use_color)
         if key == "logics":
             return _dim("auto", use_color)
-        if key in ("notify", "notify_preview", "scrub_env"):
+        if key in ("notify", "notify_preview", "scrub_env", "shared_memory", "retro"):
             return _style("off", "2", use_color)
         return _dim("default", use_color)
     value = launch.get(key)

package/src/commands/launch.py

@@ -6,6 +6,7 @@ Split out of cli_commands.py. Moved verbatim; re-exported by cli_commands.
 import os
 import shlex
 
+from .. import retro, shared_memory
 from ..agent_notify import notifications_enabled, provision, supports_agent_alerts
 from ..cli_args import CAN_RESUME_USAGE, HANDOFF_USAGE, RESUME_USAGE, _parse_json_flag
 from ..cli_helpers import (
@@ -19,7 +20,7 @@ from ..cli_helpers import (
     _write_update_notice,
 )
 from ..cli_render import _dim, _info, _success, _warn
-from ..config import PROVIDER_CODEX
+from ..config import PROVIDER_CLAUDE, PROVIDER_CODEX
 from ..errors import CdxError
 from ..handoff import HandoffSourceError, launch_prompt, load_entry, prepare_entry, resolve_source
 from ..interactive_usage import extract_interactive_usage, transcript_predates_run, usage_delta
@@ -33,12 +34,24 @@ from ..provider_runtime import (
 from ..run_command import PROMPT_STDIN, read_run_prompt
 from ..run_usage import estimate_cost
 
-LAUNCH_USAGE = "Usage: cdx <name> [--dir PATH] [--prompt TEXT|--prompt-file PATH] [--resume] [--json]"
+LAUNCH_USAGE = "Usage: cdx <name> [--dir PATH] [--prompt TEXT|--prompt-file PATH|--task TEXT [--end-state TEXT]] [--resume] [--json]"
+
+#: The first message of a session started with --task. The end state is what the
+#: user's go-ahead covers: a bare "show me first" made sessions stop after a commit
+#: and wait for a push they could have made.
+TASK_PROMPT = """Task: {task}
+
+{end_state}
+
+Before starting, read this repository's instructions (AGENTS.md, CLAUDE.md and what they reference) and use its skills where one fits; they override general habits."""
+END_STATE = """End state: {end_state}
+Reaching it is approved: take every step it needs, including the commits, pushes or pull requests it names, without asking again. Stop and ask only for a decision it does not cover."""
+NO_END_STATE = """No end state was given: stop and show the result before any commit, push or pull request."""
 
 
 def _parse_launch_args(args):
     """Return the per-launch directory, initial prompt source and ordinary launch flags."""
-    values = {"--dir": None, "--prompt": None, "--prompt-file": None}
+    values = {"--dir": None, "--prompt": None, "--prompt-file": None, "--task": None, "--end-state": None}
     cleaned = []
     index = 0
     while index < len(args):
@@ -59,6 +72,13 @@ def _parse_launch_args(args):
         values[flag] = value
     if values["--prompt"] is not None and values["--prompt-file"] is not None:
         raise CdxError("cdx <name>: --prompt and --prompt-file are mutually exclusive.")
+    if values["--end-state"] is not None and values["--task"] is None:
+        raise CdxError("cdx <name>: --end-state goes with --task.")
+    if values["--task"] is not None:
+        if values["--prompt"] is not None or values["--prompt-file"] is not None:
+            raise CdxError("cdx <name>: --task replaces --prompt and --prompt-file.")
+        end = END_STATE.format(end_state=values["--end-state"]) if values["--end-state"] else NO_END_STATE
+        values["--prompt"] = TASK_PROMPT.format(task=values["--task"], end_state=end)
     if values["--prompt-file"] == PROMPT_STDIN:
         raise CdxError("cdx <name>: --prompt-file - is not supported; the interactive session needs standard input.")
     prompt = {"prompt": values["--prompt"], "prompt_file": values["--prompt-file"]}
@@ -202,6 +222,21 @@ def _notification_provisioning_enabled(session, ctx, json_flag):
     return True
 
 
+def _link_shared_memory(session, ctx, cwd, json_flag):
+    if session["provider"] != PROVIDER_CLAUDE or (session.get("launch") or {}).get("shared_memory") is not True:
+        return
+    try:
+        status, detail = shared_memory.link(_get_auth_home(session), ctx["service"]["base_dir"], cwd)
+    except OSError as error:
+        status, detail = "unsupported", str(error)
+    if json_flag or status == "linked":
+        return
+    if status == "conflict":
+        detail = f"merge these files by hand first: {', '.join(detail)}"
+    message = f"Shared memory not linked for {session['name']}"
+    ctx["out"](f"{_warn(message, ctx['use_color'])} {detail}\n")
+
+
 def handle_launch(command, ctx, initial_prompt=None, resume=False, force_json=None, directory=None):
     json_flag = "--json" in ctx.get("raw_args", ctx["options"].get("raw_args", []))
     if force_json is not None:
@@ -262,6 +297,7 @@ def handle_launch(command, ctx, initial_prompt=None, resume=False, force_json=No
             # a real turn — so it gets no instruction it does not need.
             notice += " — approve them once in Codex to enable"
         ctx["out"](f"{_info(notice, ctx['use_color'])}\n")
+    _link_shared_memory(session, ctx, cwd, json_flag)
     runtime_run_id = None
 
     def runtime_lifecycle(event, info):
@@ -335,6 +371,8 @@ def handle_launch(command, ctx, initial_prompt=None, resume=False, force_json=No
     })
     if not json_flag:
         ctx["out"](f"{_goodbye_line(session, success_run_info, ctx['use_color'])}\n")
+    if retro.start(session, cwd, success_run_info.get("provider_transcript_path"), env=ctx.get("env")) and not json_flag:
+        ctx["out"](f"{_dim('Session retro started; read it later with `cdx retro`', ctx['use_color'])}\n")
     if json_flag:
         extra = {"session": ctx["service"]["get_session"](session["name"]), "cwd": cwd}
         if capability:

package/src/commands/maintenance.py

@@ -775,6 +775,7 @@ def handle_update(rest, ctx):
         package_root=ctx["options"].get("packageRoot"),
         prefix=ctx["options"].get("prefix"),
         base_prefix=ctx["options"].get("basePrefix"),
+        env=ctx.get("env"),
     )
     results = run_update_plan(plan, runner=ctx["options"].get("runUpdate"), env=ctx.get("env"))
     failed = any((result.get("returncode") != 0) for result in results)

package/src/commands/rescue.py

@@ -0,0 +1,207 @@
+"""cdx rescue: move a conversation stopped by a usage limit to an account that can go on.
+
+Everything it does already exists -- `status` knows which accounts are spent,
+the shared ranking knows which one is best, `handoff` carries a conversation
+over. This command only puts them in one step, and asks before it does.
+"""
+
+import json
+import os
+from datetime import datetime, timedelta, timezone
+
+from ..cli_helpers import _json_failure, _json_success, _write_json
+from ..cli_render import _info, _warn
+from ..errors import CdxError
+from ..session_ranking import rank_sessions
+from ..status_view import _now_timestamp, _priority_reset_timestamp
+from .launch import handle_handoff
+
+RESCUE_USAGE = "Usage: cdx rescue [<session>] [--to <target>] [--yes] [--dry-run] [--json]"
+#: A conversation stopped longer ago than this is history, not something to rescue.
+RECENT = timedelta(hours=24)
+
+
+def _parse(rest):
+    parsed = {"source": None, "target": None, "yes": False, "dry_run": False, "json": False}
+    index = 0
+    while index < len(rest):
+        arg = rest[index]
+        if arg == "--to" and index + 1 < len(rest):
+            parsed["target"] = rest[index + 1]
+            index += 1
+        elif arg in ("--yes", "-y"):
+            parsed["yes"] = True
+        elif arg == "--dry-run":
+            parsed["dry_run"] = True
+        elif arg == "--json":
+            parsed["json"] = True
+        elif not arg.startswith("-") and parsed["source"] is None:
+            parsed["source"] = arg
+        else:
+            raise CdxError(RESCUE_USAGE)
+        index += 1
+    return parsed
+
+
+def _recent(iso, now):
+    try:
+        when = datetime.fromisoformat(str(iso))
+    except (TypeError, ValueError):
+        return False
+    if when.tzinfo is None:
+        when = when.replace(tzinfo=timezone.utc)
+    return now - when <= RECENT
+
+
+#: How much of a transcript's end is read to find how it stopped.
+TAIL_BYTES = 256 * 1024
+
+
+def ended_on_limit(transcript):
+    """Whether the conversation's last word is a usage-limit error.
+
+    Claude writes an API error record (`isApiErrorMessage`, `error: rate_limit`);
+    Codex an `error` event with `codex_error_info: usage_limit_exceeded`. A normal
+    reply after it means the conversation went on, so only the last of the two
+    counts. This catches a stop before `cdx status` shows the account at 0%.
+    """
+    try:
+        with open(transcript, "rb") as handle:
+            handle.seek(max(0, os.path.getsize(transcript) - TAIL_BYTES))
+            lines = handle.read().decode("utf-8", errors="replace").splitlines()
+    except (OSError, TypeError):
+        return False
+    stopped = False
+    for line in lines:
+        try:
+            record = json.loads(line)
+        except ValueError:
+            continue
+        if not isinstance(record, dict):
+            continue
+        payload = record.get("payload") if isinstance(record.get("payload"), dict) else {}
+        if record.get("isApiErrorMessage") and record.get("error") == "rate_limit":
+            stopped = True
+        elif payload.get("type") == "error" and payload.get("codex_error_info") == "usage_limit_exceeded":
+            stopped = True
+        elif record.get("type") == "assistant" and not record.get("isApiErrorMessage"):
+            stopped = False
+        elif payload.get("type") == "message" and payload.get("role") == "assistant":
+            stopped = False
+    return stopped
+
+
+def stranded(service, rows, now=None):
+    """Sessions on a spent account whose last conversation can be handed off, newest first."""
+    now = now or datetime.now(timezone.utc)
+    found = []
+    for session in service["list_sessions"]():
+        row = rows.get(session["name"]) or {}
+        conversation = (session.get("conversation") or {}).get("id")
+        if not conversation or not _recent(row.get("last_launched_at"), now):
+            continue
+        if _rescued_since_launch(session, row):
+            continue
+        history = service["get_launch_history"](session["name"], limit=1)
+        last = history[0] if history else {}
+        cwd = last.get("cwd") or None
+        if not cwd or not os.path.isdir(cwd):
+            continue
+        spent = row.get("available_pct") == 0
+        if not spent and not ended_on_limit(last.get("provider_transcript_path")):
+            continue
+        found.append({
+            "session": session["name"], "provider": session["provider"], "conversation_id": conversation,
+            "cwd": cwd, "reset_at": row.get("reset_at"), "last_launched_at": row.get("last_launched_at"),
+        })
+    return sorted(found, key=lambda item: item["last_launched_at"] or "", reverse=True)
+
+
+def _rescued_since_launch(session, row):
+    """Already handed off, and not launched again since: rescuing it twice forks it."""
+    try:
+        rescued = datetime.fromisoformat(str((session.get("conversation") or {}).get("rescuedAt")))
+        launched = datetime.fromisoformat(str(row.get("last_launched_at")))
+        return rescued >= launched
+    except (TypeError, ValueError):
+        return False
+
+
+def pick_target(rows, source, provider):
+    """(target row, needs confirmation) for the best ready account, or (None, False).
+
+    `use` accounts first; an `ask-first` one only when no `use` account is
+    ready, and always behind a confirmation. `never` is not considered.
+    """
+    others = [row for row in rows.values() if row.get("session_name") != source]
+    ordered, _ = rank_sessions(others, _now_timestamp(), _priority_reset_timestamp,
+                               provider=provider, require_ready=True)
+    if ordered:
+        return ordered[0], False
+    asked = [{**row, "policy": "use"} for row in others if row.get("policy") == "ask-first"]
+    ordered, _ = rank_sessions(asked, _now_timestamp(), _priority_reset_timestamp,
+                               provider=provider, require_ready=True)
+    return (ordered[0], True) if ordered else (None, False)
+
+
+def handle_rescue(rest, ctx):
+    parsed = _parse(rest)
+    service = ctx["service"]
+    rows = {row["session_name"]: row for row in service["get_status_rows"](force_refresh=False)}
+    candidates = stranded(service, rows)
+    if parsed["source"]:
+        candidates = [c for c in candidates if c["session"] == parsed["source"]]
+    if not candidates:
+        message = "No conversation stopped by a usage limit in the last 24 hours."
+        if parsed["json"]:
+            _write_json(ctx, _json_success("rescue", message, plan=None, stranded=[]))
+        else:
+            ctx["out"](f"{message}\n")
+        return 0
+    source = candidates[0]
+    if parsed["target"]:
+        target = rows.get(parsed["target"])
+        if not target or target.get("policy") == "never":
+            raise CdxError(f"Cannot rescue onto {parsed['target']}: unknown account or policy never.")
+        confirm = target.get("policy") == "ask-first"
+    else:
+        target, confirm = pick_target(rows, source["session"], source["provider"])
+    if not target:
+        message = f"No ready {source['provider']} account to take over {source['session']}."
+        if parsed["json"]:
+            _write_json(ctx, _json_failure("rescue", "no_ready_account", message, stranded=candidates))
+            return 1
+        raise CdxError(message)
+    plan = {**source, "target": target["session_name"], "target_policy": target.get("policy", "use")}
+    if parsed["json"] or parsed["dry_run"]:
+        if parsed["json"]:
+            _write_json(ctx, _json_success("rescue", "Rescue plan", plan=plan, stranded=candidates))
+        else:
+            ctx["out"](_describe(plan, ctx) + "\n")
+        return 0
+    ctx["out"](_describe(plan, ctx) + "\n")
+    if confirm or not parsed["yes"]:
+        if not ctx["stdin_is_tty"]:
+            raise CdxError("cdx rescue needs a terminal to confirm; pass --yes (not enough for an ask-first account).")
+        ask = ctx.get("options", {}).get("input") or input
+        question = f"Hand {source['session']} over to {target['session_name']}"
+        question += " (policy ask-first)" if confirm else ""
+        if ask(f"{question}? [y/N] ").strip().lower() not in ("y", "yes"):
+            raise CdxError("Rescue cancelled.", exit_code=130)
+    code = handle_handoff(
+        [source["session"], target["session_name"], "--source-conversation", source["conversation_id"]],
+        {**ctx, "cwd": source["cwd"]},
+    )
+    if code == 0:
+        service["mark_conversation_rescued"](source["session"], source["conversation_id"])
+    return code
+
+
+def _describe(plan, ctx):
+    reset = f", back {plan['reset_at']}" if plan.get("reset_at") else ""
+    lines = [
+        _warn(f"{plan['session']} is out of usage{reset}", ctx["use_color"]),
+        f"  conversation {plan['conversation_id']} in {plan['cwd']}",
+        _info(f"-> {plan['target']}" + (" (ask-first)" if plan["target_policy"] == "ask-first" else ""), ctx["use_color"]),
+    ]
+    return "\n".join(lines)

package/src/commands/runs.py

@@ -193,6 +193,7 @@ def _detached_child_argv(parsed, prompt_path, session_name, cwd):
         ("--model", "model"),
         ("--kind", "kind"),
         ("--permission", "permission"),
+        ("--label", "label"),
     ):
         value = parsed.get(key)
         if value:
@@ -509,6 +510,17 @@ def handle_run_report(rest, ctx):
     }))
     return 0
 
+def _env_max_runs(ctx):
+    """CDX_MAX_RUNS as the default --max-parallel; unset, invalid or <= 0 means no limit."""
+    value = {**os.environ, **(ctx.get("env") or {})}.get("CDX_MAX_RUNS")
+    try:
+        limit = int(value) if value else 0
+    except ValueError:
+        return None
+    # 0 or negative reads as "no limit", like unset, rather than a cap of 1.
+    return limit if limit > 0 else None
+
+
 def handle_run(rest, ctx):
     registry = None
     run_id = None
@@ -563,6 +575,15 @@ def handle_run(rest, ctx):
         if parsed.get("reasoning_effort"):
             launch_updates["reasoning_effort"] = parsed["reasoning_effort"]
             launch_updates["power"] = parsed["reasoning_effort"]
+        # A detached child runs in the slot its parent already took.
+        max_parallel = None if detached_run_id else (parsed.get("max_parallel") or _env_max_runs(ctx))
+        if max_parallel:
+            # Before anything changes the session: a refused run must not leave
+            # Claude on a fresh conversation id that resume and rescue then
+            # point at. Finished native background runs are closed out first,
+            # since nothing else frees their slot.
+            _reconcile_background_runs(ctx)
+            _run_registry(ctx).check_capacity(max_parallel)
         # Claude needs its conversation id before the spec is built; Codex
         # records its own afterwards, from the rollout. Without this a headless
         # Claude run left the session with no identity and `cdx resume` fell
@@ -607,6 +628,8 @@ def handle_run(rest, ctx):
                 "stdout_path": artifacts.get("stdout_path"),
                 "stderr_path": artifacts.get("stderr_path"),
             },
+            label=parsed.get("label"),
+            max_parallel=max_parallel,
         )
         if parsed.get("detach"):
             # Delegate where the installed CLI can both start a background

package/src/commands/status.py

@@ -4,6 +4,7 @@ Split out of cli_commands.py. Moved verbatim; re-exported by cli_commands.
 """
 
 import os
+import re
 import threading
 import time
 from datetime import datetime
@@ -49,6 +50,7 @@ from ..provider_runtime import (
     _has_local_claude_auth,
     _probe_provider_auth_status,
 )
+from ..rtk_savings import rtk_saved
 from ..run_usage import (
     USAGE_KEYS,
     estimate_cost,
@@ -268,7 +270,7 @@ def _summarize_stats(entries):
         name = entry.get("session_name") or "-"
         row = rows.setdefault(name, {
             "session_name": name,
-            "provider": entry.get("provider") or "-",
+            "provider": set(),
             "launches": 0,
             "successes": 0,
             "failures": 0,
@@ -284,6 +286,7 @@ def _summarize_stats(entries):
             "input_tokens": 0,
             "cached_input_tokens": 0,
             "cache_creation_tokens": 0,
+            "cache_creation_1h_tokens": 0,
             "cache_read_tokens": 0,
             "output_tokens": 0,
             "reasoning_tokens": 0,
@@ -291,6 +294,8 @@ def _summarize_stats(entries):
             "last_started_at": None,
         })
         row["launches"] += 1
+        if entry.get("provider"):
+            row["provider"].add(entry["provider"])
         if entry.get("status") == "success":
             row["successes"] += 1
         elif entry.get("status") == "failed":
@@ -338,8 +343,10 @@ def _summarize_stats(entries):
         started = entry.get("started_at")
         if started and (not row["last_started_at"] or started > row["last_started_at"]):
             row["last_started_at"] = started
-            row["provider"] = entry.get("provider") or row["provider"]
     for row in rows.values():
+        # Every provider seen, not the last one: a project or model row often
+        # spans several.
+        row["provider"] = "+".join(sorted(row["provider"])) or "-"
         # 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
@@ -472,14 +479,43 @@ def _format_token_count(value):
         return f"{amount / 1000:.1f}K"
     return str(amount)
 
-def _format_stats(rows, totals, period=None, use_color=False, active_sessions=None):
+def _format_rtk_saved(rtk):
+    saved = _format_token_count(rtk["saved_tokens"])
+    share = f" ({rtk['saved_tokens'] * 100 // rtk['input_tokens']}% of their output)" if rtk["input_tokens"] else ""
+    return f"rtk saved {saved} tokens on {rtk['commands']:,} commands{share}."
+
+
+def _stats_group(entry, by):
+    """The project (launch folder) or the model a run is counted under."""
+    if by == "project":
+        return str(entry.get("cwd") or "").rstrip("/\\") or "-"
+    return entry.get("usage_model") or "-"
+
+
+def _project_labels(paths):
+    """The shortest trailing part of each folder that still tells it apart, so
+    /a/app and /b/app read as a/app and b/app rather than both as app."""
+    parts = {path: [p for p in re.split(r"[/\\]", path) if p] for path in paths}
+    labels = {}
+    for path, segments in parts.items():
+        for n in range(1, len(segments) + 1):
+            label = "/".join(segments[-n:])
+            if not any(other != path and "/".join(rest[-n:]) == label for other, rest in parts.items()):
+                break
+        else:
+            label = path
+        labels[path] = label
+    return labels
+
+
+def _format_stats(rows, totals, period=None, use_color=False, active_sessions=None, group_label="SESSION"):
     from ..cli_render import _format_relative_age
 
     active_sessions = active_sessions or set()
     if not rows:
         return "No launch stats for this period." if _has_history_period(period or {}) else "No launch stats."
     table = [[_style(value, "1", use_color) for value in [
-        "SESSION", "PROV.", "RUNS", "USAGE", "IN", "CACHE", "OUT", "REASON", "TOTAL", "COST~", "USD~", "TIME", "LAST"
+        group_label, "PROV.", "RUNS", "USAGE", "IN", "CACHE", "OUT", "REASON", "TOTAL", "COST~", "USD~", "TIME", "LAST"
     ]]]
     for row in rows:
         session_name = row["session_name"]
@@ -596,8 +632,18 @@ def handle_stats(rest, ctx):
     parsed = _parse_stats_args(rest, now=now)
     entries = ctx["service"]["get_launch_history"](parsed["name"], limit=0)
     entries = _filter_history_period(entries, parsed["period"])
+    if parsed["by"] != "session":
+        # Same accounting, another key: each run is regrouped, never re-priced.
+        entries = [{**entry, "session_name": _stats_group(entry, parsed["by"])} for entry in entries]
     rows = _summarize_stats(entries)
+    if parsed["by"] == "project":
+        labels = _project_labels([row["session_name"] for row in rows])
+        for row in rows:
+            row["project"] = row["session_name"]
+            row["session_name"] = labels[row["project"]]
     totals = _stats_totals(rows)
+    # rtk cannot tell which session a command ran in, so only the unfiltered view shows it.
+    rtk = None if parsed["name"] else rtk_saved(ctx["service"]["base_dir"], parsed["period"], env=ctx.get("env"))
     message = (
         f"Calculated stats for {parsed['name']}"
         if parsed["name"]
@@ -610,6 +656,8 @@ def handle_stats(rest, ctx):
             period=_public_history_period(parsed["period"]),
             stats=rows,
             totals=totals,
+            group_by=parsed["by"],
+            rtk=rtk,
             accounting={
                 "launches_unit": "history_attempts",
                 "period_policy": "whole_run_overlap",
@@ -619,8 +667,10 @@ def handle_stats(rest, ctx):
             },
         ))
         return 0
-    active_sessions = _active_session_names(ctx)
-    ctx["out"](f"{_format_stats(rows, totals, period=parsed['period'], use_color=ctx['use_color'], active_sessions=active_sessions)}\n")
+    active_sessions = _active_session_names(ctx) if parsed["by"] == "session" else set()
+    ctx["out"](f"{_format_stats(rows, totals, period=parsed['period'], use_color=ctx['use_color'], active_sessions=active_sessions, group_label=parsed['by'].upper())}\n")
+    if rows and rtk and rtk["commands"]:
+        ctx["out"](f"{_dim(_format_rtk_saved(rtk), ctx['use_color'])}\n")
     return 0
 
 def _resolve_last_launch_session(ctx):

package/src/handoff.py

@@ -48,7 +48,7 @@ def inspect_transcript(path, provider, extent=None):
     Never flatten messages: the descriptor points to the original tool evidence.
     The digest binds that evidence to the preparation boundary, even after append.
     """
-    ids, workspaces = set(), set()
+    ids, workspaces = set(), []
     last_event = None
     digest = hashlib.sha256()
     consumed = 0
@@ -88,7 +88,9 @@ def inspect_transcript(path, provider, extent=None):
                 if cwd:
                     if not isinstance(cwd, str) or not os.path.isabs(cwd):
                         raise ValueError('invalid workspace')
-                    workspaces.add(os.path.realpath(cwd))
+                    real = os.path.realpath(cwd)
+                    if real not in workspaces:
+                        workspaces.append(real)
                 stamp = record.get('timestamp')
                 if isinstance(stamp, str):
                     try:
@@ -102,24 +104,33 @@ def inspect_transcript(path, provider, extent=None):
                 consumed = handle.tell()
     except (OSError, ValueError) as error:
         raise CdxError(f'Cannot use transcript {path}: {error}') from error
-    if len(ids) != 1 or len(workspaces) != 1:
+    if len(ids) != 1 or not workspaces:
         raise CdxError(f'Transcript needs one conversation identity and workspace: {path}')
+    # A session that moved between folders (a worktree, a subfolder) keeps
+    # every one of them; it starts in the first, and may be handed off in any.
     return {
         'path': os.path.abspath(path), 'provider': provider, 'conversation_id': ids.pop(),
-        'workspace': workspaces.pop(), 'last_event_at': last_event,
+        'workspace': workspaces[0], 'workspaces': workspaces, 'last_event_at': last_event,
         'extent_bytes': consumed, 'sha256': digest.hexdigest(), 'format': 'jsonl',
         'mode': 'native',
     }
 
 
+def _in_workspace(info, workspace):
+    """The transcript as seen from `workspace`, or None if it never worked there."""
+    if workspace not in info['workspaces']:
+        return None
+    return {**info, 'workspace': workspace}
+
+
 def source_candidates(session, workspace):
     candidates = []
     for path in _native_paths(session):
         try:
-            info = inspect_transcript(path, session['provider'])
+            info = _in_workspace(inspect_transcript(path, session['provider']), workspace)
         except CdxError:
             continue
-        if info['workspace'] == workspace:
+        if info:
             candidates.append(info)
     # Event time helps humans choose; it is never an automatic selection rule.
     return sorted(candidates, key=lambda c: (c['last_event_at'] or '', c['path']), reverse=True)[:CANDIDATE_LIMIT]
@@ -163,11 +174,11 @@ def resolve_source(session, workspace, conversation_id=None, terminal_path=None,
         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'])
+            info = _in_workspace(inspect_transcript(path, session['provider']), workspace)
         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.')
+        if not info:
+            raise HandoffSourceError('Native transcript never worked in the target workspace.')
         info['provenance'] = 'explicit_native_path'
         return info
     if selected:
@@ -177,10 +188,10 @@ def resolve_source(session, workspace, conversation_id=None, terminal_path=None,
         matches = []
         for path in paths:
             try:
-                info = inspect_transcript(path, session['provider'])
+                info = _in_workspace(inspect_transcript(path, session['provider']), workspace)
             except CdxError:
                 continue
-            if info['conversation_id'] == selected and info['workspace'] == workspace:
+            if info and info['conversation_id'] == selected:
                 matches.append(info)
         if len(matches) > 1:
             raise HandoffSourceError(f'Conversation {selected} has multiple native transcripts; select --source-native-transcript PATH.', matches)