cdx-manager 0.9.9 → 0.9.11

package/src/cli_commands.py

@@ -6,11 +6,69 @@ import re
 import shlex
 import sys
 import time
-from datetime import datetime, timedelta
+from datetime import datetime
 
+from .backup_bundle import read_bundle_meta
 from .claude_refresh import _refresh_claude_sessions
+from .cli_args import (
+    CAN_RESUME_USAGE,
+    CONTEXT_USAGE,
+    DOCTOR_USAGE,
+    HANDOFF_USAGE,
+    LAST_USAGE,
+    REPAIR_USAGE,
+    RESUME_USAGE,
+    RUN_REPORT_USAGE,
+    RUN_STATUS_USAGE,
+    RUNS_USAGE,
+    STATUS_USAGE,
+    _filter_history_period,
+    _has_history_period,
+    _parse_add_args,
+    _parse_config_args,
+    _parse_configs_args,
+    _parse_copy_args,
+    _parse_export_args,
+    _parse_flag_args,
+    _parse_history_args,
+    _parse_import_args,
+    _parse_json_flag,
+    _parse_launch_setting_alias_args,
+    _parse_next_args,
+    _parse_remove_args,
+    _parse_rename_args,
+    _parse_run_args,
+    _parse_run_id_json_args,
+    _parse_runs_args,
+    _parse_select_args,
+    _parse_set_args,
+    _parse_stats_args,
+    _parse_timeout_seconds,
+    _parse_toggle_args,
+    _parse_unset_args,
+    _parse_update_args,
+    _public_history_period,
+)
+from .cli_helpers import (
+    API_SCHEMA_VERSION,
+    _build_handoff_context,
+    _format_export_report,
+    _handoff_launch_prompt,
+    _json_failure,
+    _json_success,
+    _latest_handoff_transcript_path,
+    _local_now_iso,
+    _make_export_progress,
+    _make_notify_progress,
+    _make_status_progress,
+    _read_handoff_transcript,
+    _update_notice_warnings,
+    _write_json,
+    _write_update_notice,
+)
 from .cli_render import _dim, _info, _style, _success, _warn
-from .config import PROVIDER_ANTIGRAVITY, PROVIDER_CLAUDE, PROVIDER_CODEX, PROVIDER_OLLAMA, PROVIDERS
+from .cli_view import handle_view as handle_view  # re-export for cli.py / tests
+from .config import PROVIDER_ANTIGRAVITY, PROVIDER_CLAUDE, PROVIDER_OLLAMA
 from .context_store import (
     clear_context,
     edit_context,
@@ -22,7 +80,6 @@ from .context_store import (
 )
 from .errors import CdxError
 from .health import collect_health_report, format_health_report
-from .cli_view import handle_view
 from .notify import (
     format_notify_event,
     format_scheduled_notification,
@@ -36,992 +93,20 @@ from .provider_runtime import (
     _ensure_session_authentication,
     _headless_artifact_paths,
     _list_launch_transcript_paths,
-    _normalize_reasoning_effort,
     _probe_provider_auth,
-    get_resume_capability,
     _run_headless_provider_command,
     _run_interactive_provider_command,
+    get_resume_capability,
 )
 from .repair import format_repair_report, repair_health
-from .backup_bundle import read_bundle_meta
+from .run_command import read_run_prompt, run_cdx_error_code, run_result_payload
 from .run_registry import RunRegistry, build_code_review_report
 from .run_usage import extract_run_usage
-from .run_command import read_run_prompt, run_cdx_error_code, run_result_payload
 from .status_view import _format_status_detail, _format_status_rows, format_priority_instruction, recommend_priority_rows
 from .update_check import LatestReleaseCheckError, fetch_latest_release, fetch_latest_release_or_raise, is_newer_version
 from .update_manager import build_update_plan, format_update_failure, run_update_plan, verify_updated_command
 
 
-STATUS_USAGE = "Usage: cdx status [--json] [--refresh|--cached] [--timeout SECONDS] | cdx status --small|-s [--refresh|--cached] [--timeout SECONDS] | cdx status <name> [--json] [--refresh|--cached] [--timeout SECONDS]"
-DOCTOR_USAGE = "Usage: cdx doctor [--json]"
-REPAIR_USAGE = "Usage: cdx repair [--dry-run] [--force] [--json]"
-UPDATE_USAGE = "Usage: cdx update [--check] [--yes] [--json] [--version TAG]"
-EXPORT_USAGE = "Usage: cdx export <file> [--include-auth] [--force] [--json] [--sessions name1,name2] [--passphrase-env VAR]"
-IMPORT_USAGE = "Usage: cdx import <file> [--force|--merge] [--json] [--sessions name1,name2] [--passphrase-env VAR]"
-CONTEXT_USAGE = "Usage: cdx context show|path|init|edit|clear|set [text...] [--json]"
-HANDOFF_USAGE = "Usage: cdx handoff <name> [--json] | cdx handoff <source> <target> [--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] [--priority 0..100] [--json]"
-UNSET_USAGE = "Usage: cdx unset <name>|--sessions all|a,b|--provider PROVIDER (--power|--permission|--fast|--rtk|--logics|--model|--priority|--all) [--json]"
-SETTING_ALIAS_USAGE = "Usage: cdx power|perm|fast|model <name|all|provider:PROVIDER|a,b> <value|default> [--json]"
-CONFIG_USAGE = "Usage: cdx config <name> [--json]"
-CONFIGS_USAGE = "Usage: cdx configs [--json]"
-HISTORY_USAGE = "Usage: cdx history [name] [--limit N] [--summary] [--since 7d|today|DATE] [--from DATE] [--to DATE] [--json]"
-STATS_USAGE = "Usage: cdx stats [name] [--since 7d|today|DATE] [--from DATE] [--to DATE] [--json]"
-LAST_USAGE = "Usage: cdx last [--json]"
-RESUME_USAGE = "Usage: cdx resume <name> [--json]"
-CAN_RESUME_USAGE = "Usage: cdx can-resume <name> [--json]"
-SELECT_USAGE = "Usage: cdx select --provider PROVIDER [--min-reasoning-effort minimal|low|medium|high|xhigh] [--min-power minimal|low|medium|high|xhigh] [--require-ready] [--refresh] --json"
-NEXT_USAGE = "Usage: cdx next [--json] [--refresh]"
-RUN_USAGE = "Usage: cdx run [session] --cwd PATH (--prompt-file PATH|--prompt TEXT) [--provider PROVIDER] [--model MODEL] [--kind assistant|code-review] [--reasoning-effort minimal|low|medium|high|xhigh] [--power minimal|low|medium|high|xhigh] [--permission review|default|auto|full|workspace-write|read-only|danger-full-access] [--timeout-seconds N] --json"
-RUNS_USAGE = "Usage: cdx runs [--limit N] --json"
-RUN_STATUS_USAGE = "Usage: cdx run-status <run_id> --json"
-RUN_REPORT_USAGE = "Usage: cdx run-report <run_id> --json"
-API_SCHEMA_VERSION = 1
-HANDOFF_TRANSCRIPT_CHARS = 120000
-HANDOFF_NATIVE_TRANSCRIPT_CANDIDATES = 64
-
-
-def _local_now_iso():
-    return datetime.now().astimezone().isoformat()
-
-
-def _json_success(action, message, warnings=None, **extra):
-    payload = {
-        "schema_version": API_SCHEMA_VERSION,
-        "ok": True,
-        "action": action,
-        "message": message,
-        "warnings": warnings or [],
-    }
-    payload.update(extra)
-    return payload
-
-
-def _json_failure(action, code, message, source="cdx", exit_code=1, warnings=None, **extra):
-    payload = {
-        "schema_version": API_SCHEMA_VERSION,
-        "ok": False,
-        "action": action,
-        "warnings": warnings or [],
-        "error": {
-            "source": source,
-            "code": code,
-            "message": message,
-            "exit_code": exit_code,
-        },
-    }
-    payload.update(extra)
-    return payload
-
-
-def _write_json(ctx, payload):
-    ctx["out"](f"{json.dumps(payload, indent=2)}\n")
-
-
-def _update_notice_warning(ctx):
-    notices = ctx.get("update_notices") or []
-    if not notices:
-        return None
-    warnings = _update_notice_warnings(ctx)
-    return warnings[0] if warnings else None
-
-
-def _update_notice_warnings(ctx):
-    warnings = []
-    for notice in ctx.get("update_notices") or []:
-        tool = notice.get("tool") or "cdx-manager"
-        current = notice.get("current_version") or ctx.get("version")
-        command = notice.get("update_command") or ("cdx update" if tool == "cdx-manager" else None)
-        message = f"Update available: {tool} {notice['latest_version']}"
-        if current:
-            message = f"{message} (current {current})"
-        if command:
-            message = f"{message}. Run: {command}"
-        warnings.append({
-            "code": "update_available" if tool == "cdx-manager" else f"{tool.replace('-', '_')}_update_available",
-            "message": message,
-            "tool": tool,
-            "latest_version": notice["latest_version"],
-            "current_version": current,
-            "update_command": command,
-            "url": notice.get("url"),
-        })
-    return warnings
-
-
-def _write_update_notice(ctx):
-    warnings = _update_notice_warnings(ctx)
-    if not warnings:
-        return
-    for warning in warnings:
-        ctx["out"](f"{_warn(warning['message'], ctx['use_color'])}\n")
-
-
-def _format_bytes(value):
-    if value is None:
-        return "n/a"
-    try:
-        amount = float(value)
-    except (TypeError, ValueError):
-        return str(value)
-    units = ["B", "KB", "MB", "GB", "TB"]
-    unit = units[0]
-    for unit in units:
-        if amount < 1024 or unit == units[-1]:
-            break
-        amount /= 1024
-    if unit == "B":
-        return f"{int(amount)} B"
-    return f"{amount:.1f} {unit}"
-
-
-def _format_export_report(result):
-    lines = [
-        f"Path: {result['path']}",
-        f"Sessions: {', '.join(result['session_names']) or '-'}",
-        f"Auth: {'included and encrypted' if result['include_auth'] else 'not included'}",
-        f"Bundle size: {_format_bytes(result.get('bundle_size_bytes'))}",
-    ]
-    if result.get("include_auth"):
-        lines.extend([
-            f"Auth files: {result.get('profile_file_count', 0)}",
-            f"Auth data: {_format_bytes(result.get('profile_bytes'))}",
-        ])
-    return "\n".join(lines)
-
-
-def _make_export_progress(ctx):
-    def progress(event):
-        kind = event.get("event")
-        if kind == "export_started":
-            auth = " with auth" if event.get("include_auth") else ""
-            message = f"Exporting {event.get('session_count', 0)} session(s){auth}..."
-            ctx["out"](f"{_info(message, ctx['use_color'])}\n")
-        elif kind == "session_started":
-            message = f"Collecting {event.get('session_name')}..."
-            ctx["out"](f"{_dim(message, ctx['use_color'])}\n")
-        elif kind == "profile_progress":
-            message = f"  {event.get('session_name')}: {event.get('file_count', 0)} files, {_format_bytes(event.get('bytes'))}"
-            ctx["out"](f"{_dim(message, ctx['use_color'])}\n")
-        elif kind == "encoding_started":
-            ctx["out"](f"{_dim('Encoding and encrypting bundle...', ctx['use_color'])}\n")
-        elif kind == "writing_started":
-            message = f"Writing {_format_bytes(event.get('bundle_size_bytes'))}..."
-            ctx["out"](f"{_dim(message, ctx['use_color'])}\n")
-    return progress
-
-
-def _make_status_progress(ctx):
-    progress_state = {"checked": 0, "total": 0}
-
-    def progress(event):
-        kind = event.get("event")
-        if kind == "status_started":
-            progress_state["checked"] = 0
-            progress_state["total"] = event.get("check_count", event.get("session_count", 0)) or 0
-            message = f"Resolving status for {event.get('session_count', 0)} session(s)..."
-            ctx["out"](f"{_info(message, ctx['use_color'])}\n")
-        elif kind == "session_started":
-            provider = event.get("provider") or "session"
-            message = f"Checking {event.get('session_name')} ({provider})..."
-            ctx["out"](f"{_dim(message, ctx['use_color'])}\n")
-        elif kind == "session_finished" and not event.get("cache_hit"):
-            progress_state["checked"] += 1
-            total = progress_state["total"] or progress_state["checked"]
-            message = f"Checked {event.get('session_name')} ({progress_state['checked']}/{total})."
-            ctx["out"](f"{_dim(message, ctx['use_color'])}\n")
-        elif kind == "status_finished":
-            message = f"Resolved {event.get('row_count', 0)} status row(s)."
-            ctx["out"](f"{_dim(message, ctx['use_color'])}\n")
-    return progress
-
-
-def _make_notify_progress(ctx):
-    progress_state = {"checked": 0, "total": 0}
-
-    def progress(event):
-        kind = event.get("event")
-        if kind == "notify_check_started":
-            target = event.get("session_name") or "next ready session"
-            ctx["out"](f"{_info(f'Checking notification target: {target}...', ctx['use_color'])}\n")
-        elif kind == "status_started":
-            progress_state["checked"] = 0
-            progress_state["total"] = event.get("check_count", event.get("session_count", 0)) or 0
-            message = f"Loading status for {event.get('session_count', 0)} session(s)..."
-            ctx["out"](f"{_dim(message, ctx['use_color'])}\n")
-        elif kind == "session_started":
-            provider = event.get("provider") or "session"
-            message = f"Checking {event.get('session_name')} ({provider})..."
-            ctx["out"](f"{_dim(message, ctx['use_color'])}\n")
-        elif kind == "session_finished" and not event.get("cache_hit"):
-            progress_state["checked"] += 1
-            total = progress_state["total"] or progress_state["checked"]
-            message = f"Checked {event.get('session_name')} ({progress_state['checked']}/{total})."
-            ctx["out"](f"{_dim(message, ctx['use_color'])}\n")
-        elif kind == "notify_waiting":
-            message = f"{event.get('message')}; checking again in {event.get('poll')}s..."
-            ctx["out"](f"{_dim(message, ctx['use_color'])}\n")
-    return progress
-
-
-def _latest_launch_transcript_path(session):
-    paths = _list_launch_transcript_paths(session)
-    if not paths:
-        return None
-    return max(paths, key=lambda path: (os.path.getmtime(path), path))
-
-
-def _get_session_home(session):
-    return session.get("authHome") or session.get("sessionRoot") or session.get("codexHome", "")
-
-
-def _safe_stat(path):
-    try:
-        return os.stat(path)
-    except OSError:
-        return None
-
-
-def _sort_recent_paths(paths):
-    stats = {path: stat for path, stat in ((_path, _safe_stat(_path)) for _path in set(paths)) if stat}
-    return sorted(stats, key=lambda path: (stats[path].st_mtime, path), reverse=True)
-
-
-def _collect_native_handoff_transcript_paths(session):
-    root = _get_session_home(session)
-    if not root:
-        return []
-    candidates = []
-    direct = [
-        os.path.join(root, "history.jsonl"),
-        os.path.join(root, "session_index.jsonl"),
-    ]
-    candidates.extend(path for path in direct if _safe_stat(path))
-
-    scan_roots = [
-        os.path.join(root, "sessions"),
-        os.path.join(root, ".claude", "projects"),
-        os.path.join(root, "projects"),
-    ]
-    skip_dirs = {"cache", "plugins", "skills", "memories", "sqlite", "shell_snapshots", "tmp", "__pycache__"}
-    for scan_root in scan_roots:
-        if not os.path.isdir(scan_root):
-            continue
-        for dirpath, dirnames, filenames in os.walk(scan_root):
-            dirnames[:] = [name for name in dirnames if not name.startswith(".") and name not in skip_dirs]
-            for filename in filenames:
-                if filename.endswith(".jsonl") or filename.endswith(".log"):
-                    candidates.append(os.path.join(dirpath, filename))
-    return _sort_recent_paths(candidates)[:HANDOFF_NATIVE_TRANSCRIPT_CANDIDATES]
-
-
-def _latest_handoff_transcript_path(session):
-    launch_path = _latest_launch_transcript_path(session)
-    if launch_path:
-        return launch_path
-    native_paths = _collect_native_handoff_transcript_paths(session)
-    return native_paths[0] if native_paths else None
-
-
-def _collect_handoff_text_fragments(value):
-    fragments = []
-    if isinstance(value, str):
-        text = value.strip()
-        if text:
-            fragments.append(text)
-    elif isinstance(value, list):
-        for item in value:
-            fragments.extend(_collect_handoff_text_fragments(item))
-    elif isinstance(value, dict):
-        if isinstance(value.get("text"), str):
-            fragments.extend(_collect_handoff_text_fragments(value.get("text")))
-        if isinstance(value.get("content"), (str, list, dict)):
-            fragments.extend(_collect_handoff_text_fragments(value.get("content")))
-        if isinstance(value.get("message"), dict):
-            fragments.extend(_collect_handoff_text_fragments(value.get("message")))
-        if isinstance(value.get("payload"), dict):
-            fragments.extend(_collect_handoff_text_fragments(value.get("payload")))
-    return fragments
-
-
-def _jsonl_record_to_handoff_text(record):
-    if not isinstance(record, dict):
-        return None
-    message = record.get("message") if isinstance(record.get("message"), dict) else {}
-    role = (
-        message.get("role")
-        or record.get("role")
-        or record.get("type")
-        or record.get("sender")
-        or "entry"
-    )
-    text_sources = []
-    for key in ("content", "text", "payload"):
-        if key in record:
-            text_sources.append(record.get(key))
-    for key in ("content", "text"):
-        if key in message:
-            text_sources.append(message.get(key))
-    fragments = []
-    for value in text_sources:
-        fragments.extend(_collect_handoff_text_fragments(value))
-    text = "\n".join(fragment for fragment in fragments if fragment).strip()
-    if not text:
-        return None
-    role = re.sub(r"[^A-Za-z0-9_-]+", "-", str(role).strip()).strip("-") or "entry"
-    return f"[{role}]\n{text}"
-
-
-def _read_jsonl_handoff_transcript(path):
-    entries = []
-    with open(path, "r", encoding="utf-8", errors="replace") as handle:
-        for line in handle:
-            line = line.strip()
-            if not line:
-                continue
-            try:
-                text = _jsonl_record_to_handoff_text(json.loads(line))
-            except json.JSONDecodeError:
-                text = None
-            if text:
-                entries.append(text)
-    if entries:
-        return "\n\n".join(entries)
-    with open(path, "r", encoding="utf-8", errors="replace") as handle:
-        return handle.read()
-
-
-def _read_handoff_transcript(path):
-    if path.endswith(".jsonl"):
-        content = _read_jsonl_handoff_transcript(path)
-    else:
-        with open(path, "r", encoding="utf-8", errors="replace") as handle:
-            content = handle.read()
-    if len(content) <= HANDOFF_TRANSCRIPT_CHARS:
-        return content, False
-    return content[-HANDOFF_TRANSCRIPT_CHARS:], True
-
-
-def _build_handoff_context(source, target, transcript_path, transcript, truncated=False):
-    truncation_note = (
-        "Only the tail of the previous transcript is included because the log was large."
-        if truncated else
-        "The previous transcript is included below."
-    )
-    return "\n".join([
-        "# Shared Context",
-        "",
-        "## Goal",
-        f"Resume the work from `{source['name']}` in `{target['name']}` because the source account has no usage left.",
-        "",
-        "## Current State",
-        f"- Source session: `{source['name']}` ({source['provider']})",
-        f"- Target session: `{target['name']}` ({target['provider']})",
-        f"- Transcript source: `{transcript_path}`",
-        f"- {truncation_note}",
-        "",
-        "## Previous Session Transcript",
-        transcript.rstrip(),
-        "",
-        "## Next Steps",
-        "- Read the transcript above.",
-        "- Continue the task from the latest actionable state.",
-        "- Preserve the target account authentication; do not copy source credentials.",
-    ])
-
-
-def _handoff_launch_prompt(session, install=None):
-    if session.get("provider") == PROVIDER_CODEX:
-        context_ref = "$CODEX_HOME/shared-context.md"
-    else:
-        context_ref = (install or {}).get("target_path") or os.path.join(
-            session.get("authHome") or session.get("sessionRoot") or "~",
-            "shared-context.md",
-        )
-    return (
-        f"Read {context_ref} first, then resume the previous session "
-        "from the latest actionable state. Do not ask me to paste the context again."
-    )
-
-
-def _parse_json_flag(args):
-    json_flag = "--json" in args
-    cleaned = [arg for arg in args if arg != "--json"]
-    return json_flag, cleaned
-
-
-def _parse_flag_args(args, schema, usage, positionals_key=None, max_positionals=0):
-    parsed = {spec["key"]: spec.get("default") for spec in schema.values()}
-    positionals = []
-    index = 0
-    while index < len(args):
-        arg = args[index]
-        if arg in schema:
-            spec = schema[arg]
-            if spec["type"] == "bool":
-                parsed[spec["key"]] = True
-                index += 1
-                continue
-            value, index = _read_option_value(args, index, usage)
-            parsed[spec["key"]] = spec.get("transform", lambda item: item)(value)
-            continue
-        if arg.startswith("--") and "=" in arg:
-            flag, value = arg.split("=", 1)
-            spec = schema.get(flag)
-            if not spec or spec["type"] == "bool":
-                raise CdxError(usage)
-            parsed[spec["key"]] = spec.get("transform", lambda item: item)(value)
-            index += 1
-            continue
-        if arg.startswith("-"):
-            raise CdxError(usage)
-        positionals.append(arg)
-        if len(positionals) > max_positionals:
-            raise CdxError(usage)
-        index += 1
-
-    if positionals_key is not None:
-        parsed[positionals_key] = positionals
-    return parsed
-
-
-def _parse_add_args(args):
-    parsed = _parse_flag_args(
-        args,
-        {"--model": {"key": "model", "type": "str", "default": None}},
-        "Usage: cdx add [provider] <name> [--model MODEL] [--json]",
-        positionals_key="values",
-        max_positionals=2,
-    )
-    values = parsed["values"]
-    if len(values) == 1:
-        return {"provider": PROVIDER_CODEX, "name": values[0], "model": parsed["model"]}
-    if len(values) == 2:
-        return {"provider": values[0], "name": values[1], "model": parsed["model"]}
-    raise CdxError("Usage: cdx add [provider] <name> [--model MODEL] [--json]")
-
-
-def _parse_copy_args(args):
-    if len(args) != 2:
-        raise CdxError("Usage: cdx cp <source> <dest> [--json]")
-    return {"source": args[0], "dest": args[1]}
-
-
-def _parse_rename_args(args):
-    if len(args) != 2:
-        raise CdxError("Usage: cdx ren <source> <dest> [--json]")
-    return {"source": args[0], "dest": args[1]}
-
-
-def _parse_remove_args(args):
-    parsed = _parse_flag_args(args, {
-        "--force": {"key": "force", "type": "bool", "default": False},
-    }, "Usage: cdx rmv <name> [--force] [--json]", positionals_key="names", max_positionals=1)
-    if len(parsed["names"]) != 1:
-        raise CdxError("Usage: cdx rmv <name> [--force] [--json]")
-    return {"name": parsed["names"][0], "force": parsed["force"]}
-
-
-def _parse_toggle_args(args, usage):
-    parsed = _parse_flag_args(args, {
-        "--json": {"key": "json", "type": "bool", "default": False},
-    }, usage, positionals_key="names", max_positionals=1)
-    if len(parsed["names"]) != 1:
-        raise CdxError(usage)
-    return {"name": parsed["names"][0], "json": parsed["json"]}
-
-
-def _parse_fast_value(value):
-    text = str(value).strip().lower()
-    if text in ("on", "true", "1", "yes"):
-        return True
-    if text in ("off", "false", "0", "no"):
-        return False
-    raise CdxError(SET_USAGE)
-
-
-def _parse_priority_value(value):
-    try:
-        priority = int(value)
-    except (TypeError, ValueError) as error:
-        raise CdxError(SET_USAGE) from error
-    if priority < 0 or priority > 100:
-        raise CdxError(SET_USAGE)
-    return priority
-
-
-def _parse_set_args(args):
-    parsed = _parse_flag_args(args, {
-        "--power": {"key": "power", "type": "str", "default": None},
-        "--permission": {"key": "permission", "type": "str", "default": None},
-        "--fast": {"key": "fast", "type": "str", "default": None, "transform": _parse_fast_value},
-        "--rtk": {"key": "rtk", "type": "str", "default": None, "transform": _parse_fast_value},
-        "--logics": {"key": "logics", "type": "str", "default": None, "transform": _parse_fast_value},
-        "--model": {"key": "model", "type": "str", "default": None},
-        "--priority": {"key": "priority", "type": "str", "default": None, "transform": _parse_priority_value},
-        "--sessions": {"key": "sessions", "type": "str", "default": None, "transform": _parse_set_unset_sessions},
-        "--provider": {"key": "provider", "type": "str", "default": None, "transform": lambda value: _parse_provider_filter(value, SET_USAGE)},
-        "--json": {"key": "json", "type": "bool", "default": False},
-    }, SET_USAGE, positionals_key="names", max_positionals=1)
-    if len(parsed["names"]) > 1:
-        raise CdxError(SET_USAGE)
-    if parsed["names"] and parsed["sessions"]:
-        raise CdxError(SET_USAGE)
-    if parsed["names"] and parsed["provider"]:
-        raise CdxError(SET_USAGE)
-    if not parsed["names"] and not parsed["sessions"] and not parsed["provider"]:
-        raise CdxError(SET_USAGE)
-    settings = {
-        key: parsed[key]
-        for key in ("power", "permission", "fast", "rtk", "logics", "model", "priority")
-        if parsed[key] is not None
-    }
-    if not settings:
-        raise CdxError(SET_USAGE)
-    return {
-        "name": parsed["names"][0] if parsed["names"] else None,
-        "sessions": parsed["sessions"],
-        "provider": parsed["provider"],
-        "settings": settings,
-        "json": parsed["json"],
-    }
-
-
-def _parse_unset_args(args):
-    parsed = _parse_flag_args(args, {
-        "--power": {"key": "power", "type": "bool", "default": False},
-        "--permission": {"key": "permission", "type": "bool", "default": False},
-        "--fast": {"key": "fast", "type": "bool", "default": False},
-        "--rtk": {"key": "rtk", "type": "bool", "default": False},
-        "--logics": {"key": "logics", "type": "bool", "default": False},
-        "--model": {"key": "model", "type": "bool", "default": False},
-        "--priority": {"key": "priority", "type": "bool", "default": False},
-        "--all": {"key": "all", "type": "bool", "default": False},
-        "--sessions": {"key": "sessions", "type": "str", "default": None, "transform": _parse_set_unset_sessions},
-        "--provider": {"key": "provider", "type": "str", "default": None, "transform": lambda value: _parse_provider_filter(value, UNSET_USAGE)},
-        "--json": {"key": "json", "type": "bool", "default": False},
-    }, UNSET_USAGE, positionals_key="names", max_positionals=1)
-    if len(parsed["names"]) > 1:
-        raise CdxError(UNSET_USAGE)
-    if parsed["names"] and parsed["sessions"]:
-        raise CdxError(UNSET_USAGE)
-    if parsed["names"] and parsed["provider"]:
-        raise CdxError(UNSET_USAGE)
-    if not parsed["names"] and not parsed["sessions"] and not parsed["provider"]:
-        raise CdxError(UNSET_USAGE)
-    keys = ["power", "permission", "fast", "rtk", "logics", "model", "priority"] if parsed["all"] else [
-        key for key in ("power", "permission", "fast", "rtk", "logics", "model", "priority") if parsed[key]
-    ]
-    if not keys:
-        raise CdxError(UNSET_USAGE)
-    return {
-        "name": parsed["names"][0] if parsed["names"] else None,
-        "sessions": parsed["sessions"],
-        "provider": parsed["provider"],
-        "keys": keys,
-        "json": parsed["json"],
-    }
-
-
-def _parse_config_args(args):
-    parsed = _parse_flag_args(args, {
-        "--json": {"key": "json", "type": "bool", "default": False},
-    }, CONFIG_USAGE, positionals_key="names", max_positionals=1)
-    if len(parsed["names"]) != 1:
-        raise CdxError(CONFIG_USAGE)
-    return {"name": parsed["names"][0], "json": parsed["json"]}
-
-
-def _parse_configs_args(args):
-    parsed = _parse_flag_args(args, {
-        "--json": {"key": "json", "type": "bool", "default": False},
-    }, CONFIGS_USAGE)
-    return {"json": parsed["json"]}
-
-
-def _parse_select_args(args):
-    parsed = _parse_flag_args(args, {
-        "--provider": {"key": "provider", "type": "str", "default": None, "transform": lambda value: _parse_provider_filter(value, SELECT_USAGE)},
-        "--min-reasoning-effort": {"key": "min_reasoning_effort", "type": "str", "default": None},
-        "--min-power": {"key": "min_power", "type": "str", "default": None},
-        "--require-ready": {"key": "require_ready", "type": "bool", "default": False},
-        "--refresh": {"key": "refresh", "type": "bool", "default": False},
-        "--json": {"key": "json", "type": "bool", "default": False},
-    }, SELECT_USAGE)
-    if not parsed["provider"] or not parsed["json"]:
-        raise CdxError(SELECT_USAGE)
-    effort = _normalize_reasoning_effort(
-        reasoning_effort=parsed["min_reasoning_effort"],
-        power=parsed["min_power"],
-        usage=SELECT_USAGE,
-    ).get("reasoning_effort")
-    return {
-        "provider": parsed["provider"],
-        "min_reasoning_effort": effort,
-        "require_ready": parsed["require_ready"],
-        "refresh": parsed["refresh"],
-        "json": parsed["json"],
-    }
-
-
-def _parse_next_args(args):
-    parsed = _parse_flag_args(args, {
-        "--refresh": {"key": "refresh", "type": "bool", "default": False},
-        "--json": {"key": "json", "type": "bool", "default": False},
-    }, NEXT_USAGE)
-    return {"json": parsed["json"], "refresh": parsed["refresh"]}
-
-
-def _parse_timeout_seconds(value, usage=RUN_USAGE):
-    try:
-        parsed = float(value)
-    except (TypeError, ValueError) as error:
-        raise CdxError(usage) from error
-    if parsed <= 0:
-        raise CdxError(usage)
-    return parsed
-
-
-def _normalize_run_permission(value):
-    if value is None:
-        return None
-    text = str(value).strip().lower()
-    aliases = {
-        "workspace-write": "default",
-        "read-only": "review",
-        "danger-full-access": "full",
-    }
-    text = aliases.get(text, text)
-    if text not in ("review", "default", "auto", "full"):
-        raise CdxError(RUN_USAGE)
-    return text
-
-
-def _parse_run_args(args):
-    parsed = _parse_flag_args(args, {
-        "--cwd": {"key": "cwd", "type": "str", "default": None},
-        "--prompt-file": {"key": "prompt_file", "type": "str", "default": None},
-        "--prompt": {"key": "prompt", "type": "str", "default": None},
-        "--provider": {"key": "provider", "type": "str", "default": None, "transform": lambda value: _parse_provider_filter(value, RUN_USAGE)},
-        "--model": {"key": "model", "type": "str", "default": None},
-        "--kind": {"key": "kind", "type": "str", "default": "assistant"},
-        "--reasoning-effort": {"key": "reasoning_effort", "type": "str", "default": None},
-        "--power": {"key": "power", "type": "str", "default": None},
-        "--permission": {"key": "permission", "type": "str", "default": None, "transform": _normalize_run_permission},
-        "--timeout-seconds": {"key": "timeout_seconds", "type": "str", "default": None, "transform": _parse_timeout_seconds},
-        "--json": {"key": "json", "type": "bool", "default": False},
-    }, RUN_USAGE, positionals_key="names", max_positionals=1)
-    if not parsed["json"]:
-        raise CdxError(RUN_USAGE)
-    name = parsed["names"][0] if parsed["names"] else None
-    if name and parsed["provider"]:
-        raise CdxError(RUN_USAGE)
-    if not name and not parsed["provider"]:
-        raise CdxError(RUN_USAGE)
-    if not parsed["cwd"]:
-        raise CdxError(RUN_USAGE)
-    if bool(parsed["prompt_file"]) == bool(parsed["prompt"]):
-        raise CdxError(RUN_USAGE)
-    if parsed["kind"] not in ("assistant", "code-review"):
-        raise CdxError(RUN_USAGE)
-    effort = _normalize_reasoning_effort(
-        reasoning_effort=parsed["reasoning_effort"],
-        power=parsed["power"],
-        usage=RUN_USAGE,
-    )
-    return {
-        "name": name,
-        "provider": parsed["provider"],
-        "cwd": parsed["cwd"],
-        "prompt_file": parsed["prompt_file"],
-        "prompt": parsed["prompt"],
-        "kind": parsed["kind"],
-        "model": parsed["model"],
-        "permission": parsed["permission"],
-        "timeout_seconds": parsed["timeout_seconds"],
-        "reasoning_effort": effort.get("reasoning_effort"),
-        "power": effort.get("power"),
-    }
-
-
-def _parse_positive_int(value):
-    try:
-        parsed = int(value)
-    except (TypeError, ValueError) as error:
-        raise CdxError(HISTORY_USAGE) from error
-    if parsed < 1:
-        raise CdxError(HISTORY_USAGE)
-    return parsed
-
-
-def _local_timezone():
-    return datetime.now().astimezone().tzinfo
-
-
-def _parse_datetime_value(value, usage, end_of_day=False):
-    text = str(value or "").strip()
-    if not text:
-        raise CdxError(usage)
-    if text.endswith("Z"):
-        text = f"{text[:-1]}+00:00"
-    is_date_only = len(text) == 10 and text[4] == "-" and text[7] == "-"
-    try:
-        parsed = datetime.fromisoformat(text)
-    except ValueError as error:
-        raise CdxError(usage) from error
-    if is_date_only and end_of_day:
-        parsed = parsed.replace(hour=23, minute=59, second=59, microsecond=999999)
-    if parsed.tzinfo is None:
-        parsed = parsed.replace(tzinfo=_local_timezone())
-    return parsed.astimezone()
-
-
-def _parse_since_value(value, now, usage):
-    text = str(value or "").strip().lower()
-    if not text:
-        raise CdxError(usage)
-    if text == "today":
-        return now.replace(hour=0, minute=0, second=0, microsecond=0)
-    if text == "yesterday":
-        today = now.replace(hour=0, minute=0, second=0, microsecond=0)
-        return today - timedelta(days=1)
-    unit = text[-1:]
-    amount_text = text[:-1]
-    if unit in ("m", "h", "d", "w") and amount_text.isdigit():
-        amount = int(amount_text)
-        if amount < 1:
-            raise CdxError(usage)
-        multipliers = {
-            "m": timedelta(minutes=amount),
-            "h": timedelta(hours=amount),
-            "d": timedelta(days=amount),
-            "w": timedelta(weeks=amount),
-        }
-        return now - multipliers[unit]
-    return _parse_datetime_value(value, usage, end_of_day=False)
-
-
-def _format_period_datetime(value):
-    if value is None:
-        return None
-    return value.isoformat(timespec="seconds")
-
-
-def _parse_history_period(parsed, now):
-    since = parsed.get("since")
-    from_value = parsed.get("from")
-    to_value = parsed.get("to")
-    if since and from_value:
-        raise CdxError("Usage: cdx history cannot combine --since and --from.")
-    start = _parse_since_value(since, now, HISTORY_USAGE) if since else None
-    if from_value:
-        start = _parse_datetime_value(from_value, HISTORY_USAGE, end_of_day=False)
-    end = _parse_datetime_value(to_value, HISTORY_USAGE, end_of_day=True) if to_value else None
-    if start and end and start.timestamp() > end.timestamp():
-        raise CdxError("Usage: cdx history period start must be before period end.")
-    return {
-        "from": _format_period_datetime(start),
-        "to": _format_period_datetime(end),
-        "from_ts": start.timestamp() if start else None,
-        "to_ts": end.timestamp() if end else None,
-    }
-
-
-def _has_history_period(period):
-    return period.get("from_ts") is not None or period.get("to_ts") is not None
-
-
-def _parse_entry_timestamp(entry):
-    value = entry.get("started_at")
-    if not value:
-        return None
-    text = str(value)
-    if text.endswith("Z"):
-        text = f"{text[:-1]}+00:00"
-    try:
-        parsed = datetime.fromisoformat(text)
-    except ValueError:
-        return None
-    if parsed.tzinfo is None:
-        parsed = parsed.replace(tzinfo=_local_timezone())
-    return parsed.timestamp()
-
-
-def _filter_history_period(entries, period):
-    if not _has_history_period(period):
-        return entries
-    filtered = []
-    start = period.get("from_ts")
-    end = period.get("to_ts")
-    for entry in entries:
-        timestamp = _parse_entry_timestamp(entry)
-        if timestamp is None:
-            continue
-        if start is not None and timestamp < start:
-            continue
-        if end is not None and timestamp > end:
-            continue
-        filtered.append(entry)
-    return filtered
-
-
-def _public_history_period(period):
-    return {
-        "from": period.get("from"),
-        "to": period.get("to"),
-    }
-
-
-def _parse_history_args(args, now=None):
-    now = now or datetime.now().astimezone()
-    parsed = _parse_flag_args(args, {
-        "--limit": {"key": "limit", "type": "str", "default": 20, "transform": _parse_positive_int},
-        "--summary": {"key": "summary", "type": "bool", "default": False},
-        "--since": {"key": "since", "type": "str", "default": None},
-        "--from": {"key": "from", "type": "str", "default": None},
-        "--to": {"key": "to", "type": "str", "default": None},
-        "--json": {"key": "json", "type": "bool", "default": False},
-    }, HISTORY_USAGE, positionals_key="names", max_positionals=1)
-    period = _parse_history_period(parsed, now)
-    return {
-        "name": parsed["names"][0] if parsed["names"] else None,
-        "limit": parsed["limit"],
-        "summary": parsed["summary"],
-        "period": period,
-        "json": parsed["json"],
-    }
-
-
-def _parse_stats_args(args, now=None):
-    now = now or datetime.now().astimezone()
-    parsed = _parse_flag_args(args, {
-        "--since": {"key": "since", "type": "str", "default": None},
-        "--from": {"key": "from", "type": "str", "default": None},
-        "--to": {"key": "to", "type": "str", "default": None},
-        "--json": {"key": "json", "type": "bool", "default": False},
-    }, STATS_USAGE, positionals_key="names", max_positionals=1)
-    period = _parse_history_period(parsed, now)
-    return {
-        "name": parsed["names"][0] if parsed["names"] else None,
-        "period": period,
-        "json": parsed["json"],
-    }
-
-
-def _read_option_value(args, index, usage):
-    if index + 1 >= len(args):
-        raise CdxError(usage)
-    return args[index + 1], index + 2
-
-
-def _parse_session_names(value):
-    if value is None:
-        return None
-    names = [item.strip() for item in value.split(",") if item.strip()]
-    if not names:
-        raise CdxError("At least one session name is required in --sessions.")
-    return names
-
-
-def _parse_set_unset_sessions(value):
-    text = str(value or "").strip()
-    if not text:
-        raise CdxError("At least one session name is required in --sessions.")
-    if text.lower() == "all":
-        return "all"
-    return _parse_session_names(text)
-
-
-def _parse_provider_filter(value, usage):
-    provider = str(value or "").strip()
-    if provider not in PROVIDERS:
-        raise CdxError(usage)
-    return provider
-
-
-def _parse_launch_setting_target(value, usage):
-    text = str(value or "").strip()
-    if not text:
-        raise CdxError(usage)
-    if text == "all":
-        return {"name": None, "sessions": "all", "provider": None}
-    if text.startswith("provider:"):
-        return {"name": None, "sessions": None, "provider": _parse_provider_filter(text.split(":", 1)[1], usage)}
-    if "," in text:
-        return {"name": None, "sessions": _parse_session_names(text), "provider": None}
-    return {"name": text, "sessions": None, "provider": None}
-
-
-def _parse_launch_setting_alias_args(kind, args):
-    json_flag, cleaned = _parse_json_flag(args)
-    if len(cleaned) != 2:
-        raise CdxError(SETTING_ALIAS_USAGE)
-    target = _parse_launch_setting_target(cleaned[0], SETTING_ALIAS_USAGE)
-    value = cleaned[1]
-    field = "permission" if kind == "perm" else kind
-    if value == "default":
-        return {**target, "keys": [field], "json": json_flag, "alias": kind}
-    if field == "fast":
-        value = _parse_fast_value(value)
-    return {**target, "settings": {field: value}, "json": json_flag, "alias": kind}
-
-
-def _parse_update_args(args):
-    parsed = _parse_flag_args(args, {
-        "--check": {"key": "check", "type": "bool", "default": False},
-        "--json": {"key": "json", "type": "bool", "default": False},
-        "--yes": {"key": "yes", "type": "bool", "default": False},
-        "--version": {"key": "version", "type": "str", "default": None},
-    }, UPDATE_USAGE)
-    if parsed["check"] and parsed["version"]:
-        raise CdxError("Usage: cdx update --check cannot be combined with --version.")
-    if parsed["version"] is not None and not parsed["version"].strip():
-        raise CdxError("Usage: cdx update [--check] [--yes] [--json] [--version TAG]")
-    return parsed
-
-
-def _parse_export_args(args):
-    parsed = _parse_flag_args(args, {
-        "--include-auth": {"key": "include_auth", "type": "bool", "default": False},
-        "--force": {"key": "force", "type": "bool", "default": False},
-        "--json": {"key": "json", "type": "bool", "default": False},
-        "--sessions": {
-            "key": "session_names",
-            "type": "str",
-            "default": None,
-            "transform": _parse_session_names,
-        },
-        "--passphrase-env": {"key": "passphrase_env", "type": "str", "default": None},
-    }, EXPORT_USAGE, positionals_key="positionals", max_positionals=1)
-    parsed["file_path"] = parsed.pop("positionals")[0] if parsed["positionals"] else None
-    if not parsed["file_path"]:
-        raise CdxError(EXPORT_USAGE)
-    if parsed["passphrase_env"] and not parsed["include_auth"]:
-        raise CdxError("--passphrase-env requires --include-auth for export.")
-    return parsed
-
-
-def _parse_import_args(args):
-    parsed = _parse_flag_args(args, {
-        "--force": {"key": "force", "type": "bool", "default": False},
-        "--merge": {"key": "merge", "type": "bool", "default": False},
-        "--json": {"key": "json", "type": "bool", "default": False},
-        "--sessions": {
-            "key": "session_names",
-            "type": "str",
-            "default": None,
-            "transform": _parse_session_names,
-        },
-        "--passphrase-env": {"key": "passphrase_env", "type": "str", "default": None},
-    }, IMPORT_USAGE, positionals_key="positionals", max_positionals=1)
-    parsed["file_path"] = parsed.pop("positionals")[0] if parsed["positionals"] else None
-    if not parsed["file_path"]:
-        raise CdxError(IMPORT_USAGE)
-    if parsed["force"] and parsed["merge"]:
-        raise CdxError("--force and --merge are mutually exclusive.")
-    return parsed
-
-
 def _resolve_bundle_passphrase(ctx, env_var, prompt, confirm=False):
     env = ctx.get("env", {})
     if env_var:
@@ -1112,7 +197,7 @@ def _bootstrap_claude_setup_token(session, ctx):
             "Claude setup-token completed, but cdx could not capture the token. "
             "Run claude setup-token and save the token under credentials/default.json."
         )
-    with open(transcript_path, "r", encoding="utf-8", errors="replace") as handle:
+    with open(transcript_path, encoding="utf-8", errors="replace") as handle:
         transcript = handle.read()
     token = _extract_claude_oauth_token(transcript)
     if not token:
@@ -1354,22 +439,6 @@ def handle_next(rest, ctx):
     return 0
 
 
-def _parse_runs_args(rest):
-    return _parse_flag_args(rest, {
-        "--limit": {"key": "limit", "type": "str", "default": 20, "transform": _parse_positive_int},
-        "--json": {"key": "json", "type": "bool", "default": False},
-    }, RUNS_USAGE, max_positionals=0)
-
-
-def _parse_run_id_json_args(rest, usage):
-    parsed = _parse_flag_args(rest, {
-        "--json": {"key": "json", "type": "bool", "default": False},
-    }, usage, positionals_key="ids", max_positionals=1)
-    if not parsed["json"] or len(parsed["ids"]) != 1:
-        raise CdxError(usage)
-    return {"run_id": parsed["ids"][0], "json": True}
-
-
 def _run_registry(ctx):
     return RunRegistry(ctx["service"]["base_dir"])
 
@@ -2533,16 +1602,6 @@ def handle_status(rest, ctx):
         }
         for item in refresh_result.get("errors", [])
     ]
-    warnings.extend([
-        {
-            "code": "claude_refresh_failed",
-            "session": item.get("session") or "unknown",
-            "message": item.get("error") or "unknown error",
-        }
-        for item in refresh_errors
-    ])
-    warnings.extend(_update_notice_warnings(ctx))
-
     status_progress = None if parsed["json"] else _make_status_progress(ctx)
     if len(args) == 1:
         row = ctx["service"]["get_status_row"](
@@ -2552,11 +1611,16 @@ def handle_status(rest, ctx):
             cache_only=parsed["cached"],
             status_timeout_seconds=parsed["timeout"],
         )
+        output_warnings = [
+            *warnings,
+            *_refresh_warning_payloads(refresh_errors, [row]),
+            *_update_notice_warnings(ctx),
+        ]
         if parsed["json"]:
-            _write_json(ctx, _json_success("status", f"Collected status for {args[0]}", warnings=warnings, session=row))
+            _write_json(ctx, _json_success("status", f"Collected status for {args[0]}", warnings=output_warnings, session=row))
             return 0
         ctx["out"](f"{_format_status_detail(row, use_color=ctx['use_color'])}\n")
-        _write_refresh_warnings(refresh_errors, ctx)
+        _write_refresh_warnings(refresh_errors, ctx, rows=[row])
         _write_update_notice(ctx)
         return 0
 
@@ -2566,11 +1630,16 @@ def handle_status(rest, ctx):
         cache_only=parsed["cached"],
         status_timeout_seconds=parsed["timeout"],
     )
+    output_warnings = [
+        *warnings,
+        *_refresh_warning_payloads(refresh_errors, rows),
+        *_update_notice_warnings(ctx),
+    ]
     if parsed["json"]:
-        _write_json(ctx, _json_success("status", "Collected session status rows", warnings=warnings, rows=rows))
+        _write_json(ctx, _json_success("status", "Collected session status rows", warnings=output_warnings, rows=rows))
         return 0
     ctx["out"](f"{_format_status_rows(rows, use_color=ctx['use_color'], small=parsed['small'])}\n")
-    _write_refresh_warnings(refresh_errors, ctx)
+    _write_refresh_warnings(refresh_errors, ctx, rows=rows)
     _write_update_notice(ctx)
     return 0
 
@@ -2595,7 +1664,7 @@ def _refresh_claude_auth_states(service, target_names=None, spawn_sync=None, env
                 env_override=env_override,
             )
             now = _local_now_iso()
-            service["update_auth_state"](session["name"], lambda auth: {
+            service["update_auth_state"](session["name"], lambda auth, authenticated=authenticated, now=now: {
                 **auth,
                 "status": "authenticated" if authenticated else "logged_out",
                 "lastCheckedAt": now,
@@ -2607,12 +1676,65 @@ def _refresh_claude_auth_states(service, target_names=None, spawn_sync=None, env
     return {"updated": updated, "errors": errors}
 
 
-def _write_refresh_warnings(refresh_errors, ctx, stream="out"):
-    write = ctx["err"] if stream == "err" and "err" in ctx else ctx["out"]
+def _rows_by_session(rows):
+    return {
+        row.get("session_name"): row
+        for row in (rows or [])
+        if row.get("session_name")
+    }
+
+
+def _is_invalid_claude_usage_auth(error):
+    text = str(error or "").lower()
+    return "http 401" in text and "invalid authentication credentials" in text
+
+
+def _has_valid_local_claude_auth(item, rows_by_name):
+    session = item.get("session")
+    row = rows_by_name.get(session)
+    return bool(row and row.get("provider") == PROVIDER_CLAUDE and row.get("auth_status") == "authenticated")
+
+
+def _refresh_warning_payloads(refresh_errors, rows=None):
+    rows_by_name = _rows_by_session(rows)
+    warnings = []
     for item in refresh_errors:
         session = item.get("session") or "unknown"
         error = item.get("error") or "unknown error"
-        write(f"{_warn(f'Warning: Claude refresh failed for {session}: {error}', ctx['use_color'])}\n")
+        warning = {
+            "code": "claude_refresh_failed",
+            "session": session,
+            "message": error,
+        }
+        if _is_invalid_claude_usage_auth(error) and _has_valid_local_claude_auth(item, rows_by_name):
+            warning.update({
+                "auth_status": "authenticated",
+                "status_freshness": "stale",
+                "message": (
+                    "Claude quota refresh failed, but local Claude auth is still valid; "
+                    f"cached quota may be stale. Original error: {error}"
+                ),
+            })
+        warnings.append(warning)
+    return warnings
+
+
+def _format_refresh_warning(item, rows_by_name):
+    session = item.get("session") or "unknown"
+    error = item.get("error") or "unknown error"
+    if _is_invalid_claude_usage_auth(error) and _has_valid_local_claude_auth(item, rows_by_name):
+        return (
+            f"Warning: Claude quota refresh failed for {session}, but local auth is still valid; "
+            f"cached quota may be stale. ({error})"
+        )
+    return f"Warning: Claude refresh failed for {session}: {error}"
+
+
+def _write_refresh_warnings(refresh_errors, ctx, stream="out", rows=None):
+    write = ctx["err"] if stream == "err" and "err" in ctx else ctx["out"]
+    rows_by_name = _rows_by_session(rows)
+    for item in refresh_errors:
+        write(f"{_warn(_format_refresh_warning(item, rows_by_name), ctx['use_color'])}\n")
 
 
 def handle_export(rest, ctx):