cdx-manager 0.12.4 → 0.15.0

package/src/session_service.py

@@ -1,89 +1,128 @@
-import base64
-import binascii
+#!/usr/bin/env python3
+"""Session service: session CRUD, launch settings, runtime, auth, and assembly.
+
+`create_session_service` returns the interface dict every caller uses; the
+functions behind it live here, or in one of the modules this re-exports from.
+
+Why the split stops here. `req_027` measured the coupling between the six
+concern groups by transitive closure and cut only where it was real:
+
+    group      entry lines   helpers reached only from it
+    status             264   16     -> src/session_status.py
+    backup             179    9     -> src/session_backup.py
+    crud               235    3     stays
+    settings            58    1     stays
+    runtime            115    0     stays
+    auth                10    0     stays
+
+`runtime` and `auth` have **no** helper of their own. Made into modules they
+would be thin wrappers over imports from here, which reads worse than leaving
+them in place; `crud` is the core the others build on. If you are about to
+finish the job by splitting the remaining four, re-measure first - that is the
+evidence that says not to.
+
+The `# noqa: F401` markers below are load-bearing: without them ruff removes
+the re-exports as unused and callers importing through this module break.
+`test_session_service_facade_still_exposes_every_name_its_callers_import`
+guards that.
+"""
 import json
 import os
 import shutil
-import sys
 import tempfile
 import uuid
-from concurrent.futures import ThreadPoolExecutor, as_completed
-from datetime import datetime, timezone
-from urllib.parse import quote
+from functools import partial
 
-from .backup_bundle import decode_bundle, encode_bundle
-from .claude_usage import _decode_jwt_claims
 from .codex_usage import fetch_codex_rate_limits
-from .config import PROVIDER_ANTIGRAVITY, PROVIDER_CLAUDE, PROVIDER_CODEX, PROVIDERS, get_cdx_home
+from .config import (
+    MAX_LAUNCH_BUDGET_USD,
+    MAX_LAUNCH_EXTRA_ARGS_LENGTH,
+    PERMISSION_INPUT_VALUES,
+    PERMISSION_VALUES,
+    PROVIDER_CLAUDE,
+    PROVIDER_CODEX,
+    REASONING_EFFORT_VALUES,
+    get_cdx_home,
+    normalize_permission,
+    split_extra_args,
+)
 from .errors import CdxError
 from .fs_utils import atomic_write, remove_tree
+from .session_backup import (  # noqa: F401  (re-exported for callers and tests)
+    _FORCE_IMPORT_PRESERVED_PROFILE_PATHS,
+    _auth_bundle_paths,
+    _build_export_session_record,
+    _collect_auth_files,
+    _force_import_preserved_profile_paths,
+    _resolve_session_subset,
+    _restore_force_import_profile_paths,
+    _restore_import_backup,
+    _safe_relpath,
+    _validate_import_profile_files,
+    export_bundle,
+    import_bundle,
+)
+from .session_helpers import (  # noqa: F401  (re-exported for src/__init__.py, callers and tests)
+    ALLOWED_PROVIDERS,
+    DEFAULT_PROVIDER,
+    MAX_SESSION_NAME_LENGTH,
+    RESERVED_SESSION_NAMES,
+    _encode,
+    _ensure_private_dir,
+    _get_global_codex_home,
+    _get_session_auth_home,
+    _get_session_root,
+    _local_now_iso,
+    _normalize_provider,
+    _process_is_running,
+    _runtime_is_active,
+    _session_runtime,
+    _validate_new_session_name,
+    list_sessions,
+)
+from .session_status import (  # noqa: F401  (re-exported for callers and tests)
+    CLAUDE_STATUS_CACHE_TTL_SECONDS,
+    CODEX_STATUS_CACHE_TTL_SECONDS,
+    MAX_STATUS_WORKERS,
+    STATUS_CACHE_TTL_SECONDS,
+    _compute_available_pct,
+    _fetch_codex_status,
+    _is_low_confidence_status_source,
+    _is_status_cache_fresh,
+    _is_status_newer,
+    _merge_status_payload,
+    _normalize_pct_value,
+    _normalize_status_payload,
+    _parse_status_timestamp,
+    _read_expected_account_email,
+    _resolve_row_session,
+    _resolve_session_status,
+    _row_priority,
+    _row_reasoning_effort,
+    _status_cache_hit,
+    _status_cache_ttl_seconds,
+    _status_has_more_detail,
+    _status_row_from_session,
+    _to_local_iso,
+    format_list_rows,
+    get_status_row,
+    get_status_rows,
+    record_status,
+)
 from .session_store import create_session_store
-from .status_source import find_latest_status_artifact
+from .status_source import find_latest_codex_conversation_id
 
-DEFAULT_PROVIDER = PROVIDER_CODEX
-ALLOWED_PROVIDERS = set(PROVIDERS)
-MAX_SESSION_NAME_LENGTH = 64
 MAX_SESSION_LABEL_LENGTH = 64
-RESERVED_SESSION_NAMES = {
-    "add",
-    "can-resume",
-    "clean",
-    "context",
-    "configs",
-    "cp",
-    "disable",
-    "disk",
-    "doctor",
-    "enable",
-    "export",
-    "fast",
-    "help",
-    "handoff",
-    "history",
-    "import",
-    "last",
-    "label",
-    "login",
-    "logout",
-    "memory",
-    "model",
-    "mv",
-    "next",
-    "notify",
-    "perm",
-    "power",
-    "ready",
-    "repair",
-    "reset",
-    "resume",
-    "ren",
-    "rename",
-    "rmv",
-    "run",
-    "select",
-    "config",
-    "set",
-    "stats",
-    "status",
-    "unset",
-    "update",
-    "view",
-    "version",
-    "--help",
-    "-h",
-    "--version",
-    "-v",
-}
-STATUS_CACHE_TTL_SECONDS = 60
-CLAUDE_STATUS_CACHE_TTL_SECONDS = 10 * 60
 # Each live Codex probe spawns app-server, which can refresh+rotate the OAuth
 # token. Cache longer so routine status calls don't keep triggering refreshes.
-CODEX_STATUS_CACHE_TTL_SECONDS = 5 * 60
-_FORCE_IMPORT_PRESERVED_PROFILE_PATHS = ("plugins",)
 STATUS_PROBE_TIMEOUT_SECONDS = 5
-MAX_STATUS_WORKERS = 8
-LAUNCH_POWER_VALUES = {"minimal", "low", "medium", "high", "xhigh"}
-LAUNCH_REASONING_EFFORT_VALUES = {"minimal", "low", "medium", "high", "xhigh"}
-LAUNCH_PERMISSION_VALUES = {"review", "default", "auto", "full"}
+# References to the shared definitions in config, not copies. These used to be
+# three separate literals here, validated independently of the ones `cdx run`
+# uses, which is how `cdx set` and `cdx run` came to disagree about the same
+# setting.
+LAUNCH_POWER_VALUES = REASONING_EFFORT_VALUES
+LAUNCH_REASONING_EFFORT_VALUES = REASONING_EFFORT_VALUES
+LAUNCH_PERMISSION_VALUES = PERMISSION_VALUES
 MAX_LAUNCH_MODEL_LENGTH = 128
 MIN_LAUNCH_PRIORITY = 0
 MAX_LAUNCH_PRIORITY = 100
@@ -93,25 +132,6 @@ DEFAULT_LAUNCH_SETTINGS = {
 }
 
 
-def _encode(name):
-    return quote(name, safe="")
-
-
-def _ensure_private_dir(path):
-    os.makedirs(path, exist_ok=True)
-    if sys.platform == "win32":
-        return
-    try:
-        os.chmod(path, 0o700)
-    except OSError:
-        pass
-
-
-def _get_global_codex_home(env=None):
-    env = env or os.environ
-    return env.get("CODEX_HOME") or os.path.join(os.path.expanduser("~"), ".codex")
-
-
 def _seed_codex_auth_from_global(auth_home, env=None):
     source_home = _get_global_codex_home(env)
     source_auth = os.path.join(source_home, "auth.json")
@@ -137,9 +157,17 @@ def _normalize_launch_settings(settings, mark_fast_service_tier=True):
             raise CdxError(f"Unsupported reasoning effort: {settings['reasoning_effort']}")
         normalized["reasoning_effort"] = effort
     if "permission" in settings and settings["permission"] is not None:
-        permission = str(settings["permission"]).strip().lower()
-        if permission not in LAUNCH_PERMISSION_VALUES:
-            raise CdxError(f"Unsupported permission: {settings['permission']}")
+        # Accepts the provider-native aliases (workspace-write, read-only,
+        # danger-full-access) exactly as `cdx run --permission` does, and stores
+        # the canonical value, so nothing downstream has to learn the aliases.
+        # They used to work on `run` only, so a value copied from one command to
+        # the other was rejected.
+        permission = normalize_permission(settings["permission"])
+        if permission is None:
+            allowed = "|".join(PERMISSION_INPUT_VALUES)
+            raise CdxError(
+                f"Unsupported permission: {settings['permission']} (allowed values: {allowed})"
+            )
         normalized["permission"] = permission
     if "fast" in settings and settings["fast"] is not None:
         value = settings["fast"]
@@ -190,6 +218,40 @@ def _normalize_launch_settings(settings, mark_fast_service_tier=True):
         if len(model) > MAX_LAUNCH_MODEL_LENGTH or any(ord(ch) < 32 or ord(ch) == 127 for ch in model):
             raise CdxError("Model contains unsupported characters.")
         normalized["model"] = model
+    if "fallback_model" in settings and settings["fallback_model"] is not None:
+        # Claude accepts a comma-separated list here and tries each in order, so
+        # this validates every element rather than the string as one model name.
+        raw = str(settings["fallback_model"]).strip()
+        if not raw:
+            raise CdxError("Fallback model cannot be empty.")
+        elements = [element.strip() for element in raw.split(",")]
+        if any(not element for element in elements):
+            raise CdxError("Fallback model cannot contain an empty entry.")
+        for element in elements:
+            if len(element) > MAX_LAUNCH_MODEL_LENGTH or any(ord(ch) < 32 or ord(ch) == 127 for ch in element):
+                raise CdxError("Fallback model contains unsupported characters.")
+        normalized["fallback_model"] = ",".join(elements)
+    if "extra_args" in settings and settings["extra_args"] is not None:
+        extra = str(settings["extra_args"]).strip()
+        if not extra:
+            raise CdxError("Extra args cannot be empty.")
+        if len(extra) > MAX_LAUNCH_EXTRA_ARGS_LENGTH or any(ord(ch) < 32 or ord(ch) == 127 for ch in extra):
+            raise CdxError("Extra args contain unsupported characters.")
+        # Parsed here, not at launch: a string that cannot be split into argv
+        # should be rejected when it is set, not when a run fails days later.
+        if split_extra_args(extra) is None:
+            raise CdxError("Extra args are not a valid argument list (unbalanced quotes).")
+        normalized["extra_args"] = extra
+    if "budget" in settings and settings["budget"] is not None:
+        try:
+            budget = float(settings["budget"])
+        except (TypeError, ValueError) as error:
+            raise CdxError(f"Unsupported budget: {settings['budget']}") from error
+        # NaN fails every comparison below, so it has to be rejected explicitly
+        # or it would sail through the range check.
+        if budget != budget or budget <= 0 or budget > MAX_LAUNCH_BUDGET_USD:
+            raise CdxError(f"Unsupported budget: {settings['budget']}")
+        normalized["budget"] = budget
     if "priority" in settings and settings["priority"] is not None:
         try:
             priority = int(settings["priority"])
@@ -201,102 +263,6 @@ def _normalize_launch_settings(settings, mark_fast_service_tier=True):
     return normalized
 
 
-def _local_now_iso():
-    return datetime.now().astimezone().isoformat()
-
-
-def _process_is_running(pid):
-    try:
-        pid = int(pid)
-    except (TypeError, ValueError):
-        return False
-    if pid <= 0:
-        return False
-    try:
-        os.kill(pid, 0)
-    except ProcessLookupError:
-        return False
-    except PermissionError:
-        return True
-    except OSError:
-        return False
-    return True
-
-
-def _safe_relpath(path):
-    normalized = os.path.normpath(str(path or "").replace("\\", "/")).replace("\\", "/")
-    if (
-        not normalized
-        or normalized == "."
-        or normalized.startswith("/")
-        or (len(normalized) > 1 and normalized[1] == ":")
-        or normalized == ".."
-        or normalized.startswith("../")
-    ):
-        raise CdxError("Bundle contains an unsafe file path.")
-    return normalized
-
-
-def _to_local_iso(value):
-    if not value:
-        return value
-    try:
-        parsed = datetime.fromisoformat(str(value).replace("Z", "+00:00"))
-    except (TypeError, ValueError):
-        return value
-    if parsed.tzinfo is None:
-        parsed = parsed.replace(tzinfo=timezone.utc)
-    return parsed.astimezone().isoformat()
-
-
-def _normalize_pct_value(value):
-    if value is None:
-        return None
-    try:
-        return max(0, min(100, round(float(value))))
-    except (TypeError, ValueError):
-        return None
-
-
-def _normalize_status_payload(payload=None):
-    if payload is None:
-        payload = {}
-    now = _local_now_iso()
-    return {
-        "usage_pct": _normalize_pct_value(payload.get("usage_pct")),
-        "remaining_5h_pct": _normalize_pct_value(payload.get("remaining_5h_pct")),
-        "remaining_week_pct": _normalize_pct_value(payload.get("remaining_week_pct")),
-        "credits": payload.get("credits"),
-        "reset_credits_available": payload.get("reset_credits_available"),
-        "reset_credits": payload.get("reset_credits"),
-        "reset_5h_at": payload.get("reset_5h_at"),
-        "reset_week_at": payload.get("reset_week_at"),
-        "reset_at": payload.get("reset_at") or payload.get("reset_week_at") or payload.get("reset_5h_at"),
-        "updated_at": _to_local_iso(payload.get("updated_at") or payload.get("captured_at") or now),
-        "raw_status_text": payload.get("raw_status_text"),
-        "source_ref": payload.get("source_ref"),
-        "structured": bool(payload.get("structured")),
-    }
-
-
-def _parse_status_timestamp(value):
-    if not value:
-        return None
-    try:
-        return datetime.fromisoformat(str(value).replace("Z", "+00:00"))
-    except (TypeError, ValueError):
-        return None
-
-
-def _status_cache_ttl_seconds(session, ttl_seconds=STATUS_CACHE_TTL_SECONDS):
-    if ttl_seconds == STATUS_CACHE_TTL_SECONDS:
-        if session.get("provider") == PROVIDER_CLAUDE:
-            return CLAUDE_STATUS_CACHE_TTL_SECONDS
-        if session.get("provider") == PROVIDER_CODEX:
-            return CODEX_STATUS_CACHE_TTL_SECONDS
-    return ttl_seconds
-
-
 def _parse_status_timeout_seconds(value):
     if value in (None, ""):
         return None
@@ -309,131 +275,6 @@ def _parse_status_timeout_seconds(value):
     return parsed
 
 
-def _is_status_cache_fresh(session, ttl_seconds=STATUS_CACHE_TTL_SECONDS):
-    status = session.get("lastStatus") or {}
-    if _is_low_confidence_status_source(status):
-        return False
-    updated_at = _parse_status_timestamp(status.get("updated_at") or session.get("lastStatusAt"))
-    if not updated_at:
-        return False
-    now = datetime.now(timezone.utc).astimezone()
-    ttl_seconds = _status_cache_ttl_seconds(session, ttl_seconds)
-    return (now - updated_at.astimezone(now.tzinfo)).total_seconds() < ttl_seconds
-
-
-def _is_status_newer(candidate, current):
-    if not candidate:
-        return False
-    if not current:
-        return True
-    candidate_at = _parse_status_timestamp(candidate.get("updated_at"))
-    current_at = _parse_status_timestamp(current.get("updated_at"))
-    if candidate_at and current_at:
-        return candidate_at > current_at
-    if candidate_at:
-        return True
-    return False
-
-
-def _status_has_more_detail(candidate, current):
-    if not candidate:
-        return False
-    if not current:
-        return True
-
-    fields = [
-        "usage_pct",
-        "remaining_5h_pct",
-        "remaining_week_pct",
-        "credits",
-        "reset_credits_available",
-        "reset_credits",
-        "reset_5h_at",
-        "reset_week_at",
-        "reset_at",
-        "raw_status_text",
-        "source_ref",
-    ]
-    return any(current.get(field) is None and candidate.get(field) is not None for field in fields)
-
-
-def _merge_status_payload(current, candidate):
-    if not current:
-        return candidate
-    if not candidate:
-        return current
-
-    merged = dict(current)
-    for field in [
-        "usage_pct",
-        "remaining_5h_pct",
-        "remaining_week_pct",
-        "credits",
-        "reset_credits_available",
-        "reset_credits",
-        "reset_5h_at",
-        "reset_week_at",
-        "reset_at",
-        "raw_status_text",
-        "source_ref",
-    ]:
-        if merged.get(field) is None and candidate.get(field) is not None:
-            merged[field] = candidate[field]
-
-    # The structured marker qualifies the source_ref; keep them in sync when
-    # the merge adopts the candidate's ref, else a structured rollout ref
-    # would read as low-confidence scraped text.
-    if merged.get("source_ref") is not None and merged["source_ref"] == candidate.get("source_ref"):
-        merged["structured"] = bool(candidate.get("structured"))
-
-    merged["updated_at"] = candidate.get("updated_at") or current.get("updated_at")
-    return merged
-
-
-def _compute_available_pct(status):
-    if not status:
-        return None
-    values = [
-        _normalize_pct_value(status.get("remaining_5h_pct")),
-        _normalize_pct_value(status.get("remaining_week_pct")),
-    ]
-    values = [value for value in values if value is not None]
-    if not values:
-        return None
-    return min(values)
-
-
-def _is_low_confidence_status_source(status):
-    if not status:
-        return False
-    if status.get("structured"):
-        # Exact rate_limits API data: trustworthy even when it comes from a
-        # sessions/rollout path, which otherwise flags scraped-text noise.
-        return False
-    source_ref = str(status.get("source_ref") or "").replace(os.sep, "/")
-    return "/sessions/" in source_ref and "/rollout" in source_ref
-
-
-def _read_expected_account_email(auth_home):
-    auth_path = os.path.join(auth_home, "auth.json")
-    try:
-        with open(auth_path, encoding="utf-8") as handle:
-            auth = json.load(handle)
-    except (FileNotFoundError, OSError, json.JSONDecodeError):
-        return None
-
-    tokens = auth.get("tokens") or {}
-    for token_name in ("id_token", "access_token"):
-        claims = _decode_jwt_claims(tokens.get(token_name))
-        email = claims.get("email")
-        if not email and token_name == "access_token":
-            profile = claims.get("https://api.openai.com/profile") or {}
-            email = profile.get("email")
-        if email:
-            return str(email).strip().lower()
-    return None
-
-
 def _ensure_claude_attribution_disabled(auth_home):
     settings_dir = os.path.join(auth_home, ".claude")
     settings_path = os.path.join(settings_dir, "settings.json")
@@ -455,1151 +296,582 @@ def _ensure_claude_attribution_disabled(auth_home):
     return True
 
 
-def create_session_service(options=None):
-    if options is None:
-        options = {}
-    env = options.get("env", os.environ)
-    base_dir = options.get("base_dir") or get_cdx_home(env)
-    store = options.get("store") or create_session_store(base_dir)
-    custom_codex_status_fetcher = options.get("fetchCodexRateLimits")
-    codex_status_fetcher = custom_codex_status_fetcher or fetch_codex_rate_limits
-    default_status_timeout_seconds = (
-        _parse_status_timeout_seconds(options.get("statusTimeoutSeconds"))
-        or _parse_status_timeout_seconds(env.get("CDX_STATUS_TIMEOUT_SECONDS"))
-        or STATUS_PROBE_TIMEOUT_SECONDS
-    )
-
-    def _fetch_codex_status(session, timeout_seconds=None):
-        if custom_codex_status_fetcher:
-            return custom_codex_status_fetcher(session)
-        timeout = timeout_seconds or default_status_timeout_seconds
-        return codex_status_fetcher(session, timeout=timeout)
-
-    def _get_session_root(name):
-        return os.path.join(base_dir, "profiles", _encode(name))
-
-    def _get_session_auth_home(name, provider):
-        root = _get_session_root(name)
-        if provider == PROVIDER_CLAUDE:
-            return os.path.join(root, "claude-home")
-        if provider == PROVIDER_ANTIGRAVITY:
-            return os.path.join(root, "antigravity-home")
-        return root
-
-    def _normalize_provider(provider):
-        value = provider or DEFAULT_PROVIDER
-        if value not in ALLOWED_PROVIDERS:
-            raise CdxError(f"Unsupported provider: {value}")
-        return value
-
-    def _runtime_is_active(runtime):
-        return (
-            isinstance(runtime, dict)
-            and runtime.get("status") == "running"
-            and _process_is_running(runtime.get("pid"))
-        )
-
-    def _session_runtime(name):
-        found = {}
-
-        def updater(state):
-            if not state:
-                return None
-            runtime = state.get("runtime")
-            if _runtime_is_active(runtime):
-                found["runtime"] = runtime
-                return None
-            if isinstance(runtime, dict) and runtime.get("status") == "running":
-                return {
-                    **state,
-                    "status": "ready",
-                    "runtime": {
-                        **runtime,
-                        "status": "stale",
-                        "endedAt": _local_now_iso(),
-                    },
-                }
-            return None
+def _normalize_session_label(label):
+    text = str(label or "").strip()
+    if not text:
+        raise CdxError("Session label is required")
+    if len(text) > MAX_SESSION_LABEL_LENGTH:
+        raise CdxError(f"Session label is too long (max {MAX_SESSION_LABEL_LENGTH} characters)")
+    if any(ord(ch) < 32 or ord(ch) == 127 for ch in text):
+        raise CdxError("Session label cannot contain control characters")
+    return text
+
+
+def set_launch_settings(store, name, settings):
+    session = store["get_session"](name)
+    if not session:
+        raise CdxError(f"Unknown session: {name}")
+    updates = _normalize_launch_settings(settings)
+    if not updates:
+        raise CdxError("At least one launch setting is required.")
+    now = _local_now_iso()
 
-        store["update_session_state"](name, updater)
-        return found.get("runtime")
-
-    def _validate_new_session_name(name):
-        if not name:
-            raise CdxError("Session name is required")
-        if str(name) != str(name).strip():
-            raise CdxError("Session name cannot start or end with whitespace")
-        if str(name) in (".", ".."):
-            raise CdxError("Session name cannot be . or ..")
-        if len(str(name)) > MAX_SESSION_NAME_LENGTH:
-            raise CdxError(f"Session name is too long (max {MAX_SESSION_NAME_LENGTH} characters)")
-        if any(ord(ch) < 32 or ord(ch) == 127 for ch in str(name)):
-            raise CdxError("Session name cannot contain control characters")
-        if name in RESERVED_SESSION_NAMES:
-            raise CdxError(f"Session name is reserved: {name}")
-
-    def _normalize_session_label(label):
-        text = str(label or "").strip()
-        if not text:
-            raise CdxError("Session label is required")
-        if len(text) > MAX_SESSION_LABEL_LENGTH:
-            raise CdxError(f"Session label is too long (max {MAX_SESSION_LABEL_LENGTH} characters)")
-        if any(ord(ch) < 32 or ord(ch) == 127 for ch in text):
-            raise CdxError("Session label cannot contain control characters")
-        return text
-
-    def _build_export_session_record(session):
+    def updater(s):
+        # Build the new launch dict from the fresh record inside the store
+        # lock; a pre-lock snapshot loses a concurrent setting change.
+        current = _normalize_launch_settings(s.get("launch") or {}, mark_fast_service_tier=False)
+        launch = {**current, **updates}
+        if "power" in updates:
+            launch.pop("reasoning_effort", None)
+            launch.pop("reasoningEffort", None)
+        if "reasoning_effort" in updates:
+            launch.pop("power", None)
+        explicit_power = "power" in updates or "reasoning_effort" in updates
+        if explicit_power and "fast" not in updates and launch.get("fastMode") != "service_tier":
+            launch["fast"] = False
+            launch.pop("fastMode", None)
+        if updates.get("fast") is False:
+            launch.pop("fastMode", None)
+            if not any(key in launch for key in ("power", "reasoning_effort", "reasoningEffort")):
+                launch["power"] = DEFAULT_LAUNCH_SETTINGS["power"]
         return {
-            "name": session["name"],
-            "provider": session["provider"],
-            "label": session.get("label"),
-            "enabled": session.get("enabled", True) is not False,
-            "createdAt": session.get("createdAt"),
-            "updatedAt": session.get("updatedAt"),
-            "lastLaunchedAt": session.get("lastLaunchedAt"),
-            "lastStatusAt": session.get("lastStatusAt"),
-            "lastStatus": session.get("lastStatus"),
-            "launch": session.get("launch"),
-            "auth": session.get("auth"),
-        }
-
-    def _auth_bundle_paths(provider):
-        if provider == PROVIDER_CLAUDE:
-            return [
-                "claude-home/configs/default.json",
-                "claude-home/credentials/default.json",
-                "claude-home/.claude/.credentials.json",
-                "claude-home/.claude.json",
-                "claude-home/auth.json",
-            ]
-        return [
-            "auth.json",
-        ]
-
-    def _collect_auth_files(session_root, provider, session_name=None, progress_callback=None):
-        files = []
-        total_bytes = 0
-        if not os.path.isdir(session_root):
-            return {"files": files, "file_count": 0, "bytes": 0}
-        for rel_path in _auth_bundle_paths(provider):
-            full_path = os.path.join(session_root, rel_path)
-            if not os.path.isfile(full_path):
-                continue
-            with open(full_path, "rb") as handle:
-                raw_content = handle.read()
-                total_bytes += len(raw_content)
-                content = base64.b64encode(raw_content).decode("ascii")
-            files.append({"path": rel_path.replace(os.sep, "/"), "data_b64": content})
-            if progress_callback:
-                progress_callback({
-                    "event": "profile_progress",
-                    "session_name": session_name,
-                    "file_count": len(files),
-                    "bytes": total_bytes,
-                })
-        return {"files": files, "file_count": len(files), "bytes": total_bytes}
-
-    def _resolve_session_subset(session_names):
-        if not session_names:
-            return list_sessions()
-        by_name = {session["name"]: session for session in list_sessions()}
-        selected = []
-        for name in session_names:
-            session = by_name.get(name)
-            if not session:
-                raise CdxError(f"Unknown session: {name}")
-            selected.append(session)
-        return selected
-
-    def create_session(name, provider=DEFAULT_PROVIDER):
-        _validate_new_session_name(name)
-        normalized_provider = _normalize_provider(provider)
-        session_root = _get_session_root(name)
-        auth_home = _get_session_auth_home(name, normalized_provider)
-        _ensure_private_dir(base_dir)
-        _ensure_private_dir(os.path.join(base_dir, "profiles"))
-        _ensure_private_dir(session_root)
-        _ensure_private_dir(auth_home)
-        if normalized_provider == PROVIDER_CODEX:
-            _seed_codex_auth_from_global(auth_home, env=env)
-        if normalized_provider == PROVIDER_CLAUDE:
-            _ensure_claude_attribution_disabled(auth_home)
-        now = _local_now_iso()
-        session = {
-            "name": name,
-            "provider": normalized_provider,
-            "enabled": True,
-            "sessionRoot": session_root,
-            "authHome": auth_home,
-            "createdAt": now,
-            "updatedAt": now,
-            "lastLaunchedAt": None,
-            "lastStatusAt": None,
-            "lastStatus": None,
-            "launch": dict(DEFAULT_LAUNCH_SETTINGS),
-            "auth": {
-                "status": "unknown",
-                "lastCheckedAt": None,
-                "lastAuthenticatedAt": None,
-                "lastLoggedOutAt": None,
-            },
-        }
-        result = store["add_session"](session)
-        if not result["ok"]:
-            raise CdxError(f"Session already exists: {name}")
-        return result["session"]
-
-    def remove_session(name):
-        session = store["get_session"](name)
-        if not session:
-            raise CdxError(f"Unknown session: {name}")
-        session_root = session.get("sessionRoot") or _get_session_root(name)
-        quarantine_root = None
-        if os.path.exists(session_root):
-            profiles_dir = os.path.dirname(session_root)
-            os.makedirs(profiles_dir, exist_ok=True)
-            quarantine_root = tempfile.mkdtemp(prefix=f".{_encode(name)}.remove.", dir=profiles_dir)
-            os.rmdir(quarantine_root)
-            os.rename(session_root, quarantine_root)
-        try:
-            removed = store["remove_session"](name)
-        except Exception:
-            if quarantine_root and os.path.exists(quarantine_root) and not os.path.exists(session_root):
-                os.rename(quarantine_root, session_root)
-            raise
-        if not removed:
-            if quarantine_root and os.path.exists(quarantine_root) and not os.path.exists(session_root):
-                os.rename(quarantine_root, session_root)
-            raise CdxError(f"Unknown session: {name}")
-        if quarantine_root:
-            try:
-                remove_tree(quarantine_root)
-            except OSError as error:
-                raise CdxError(
-                    f"Removed session {name}, but failed to delete archived profile {quarantine_root}: {error}"
-                ) from error
-        return removed
-
-    def copy_session(source_name, dest_name):
-        if source_name == dest_name:
-            raise CdxError("Source and destination session names must be different")
-        _validate_new_session_name(dest_name)
-        source = store["get_session"](source_name)
-        if not source:
-            raise CdxError(f"Unknown session: {source_name}")
-        existing = store["get_session"](dest_name)
-        overwritten = False
-        source_root = source.get("sessionRoot") or _get_session_root(source_name)
-        dest_root = _get_session_root(dest_name)
-        if not existing and os.path.exists(dest_root):
-            raise CdxError(f"Session profile already exists: {dest_name}")
-        dest_auth_home = _get_session_auth_home(dest_name, source["provider"])
-        profiles_dir = os.path.dirname(dest_root)
-        os.makedirs(profiles_dir, exist_ok=True)
-        temp_parent = tempfile.mkdtemp(prefix=f".{_encode(dest_name)}.copy.", dir=profiles_dir)
-        temp_root = os.path.join(temp_parent, "profile")
-        backup_root = None
-        moved_temp = False
-        now = _local_now_iso()
-        replacement = {
-            "name": dest_name,
-            "provider": source["provider"],
-            "enabled": True,
-            "sessionRoot": dest_root,
-            "authHome": dest_auth_home,
-            "createdAt": now,
+            **s,
+            "launch": launch,
             "updatedAt": now,
-            "lastLaunchedAt": None,
-            "lastStatusAt": None,
-            "lastStatus": None,
-            **({"launch": source.get("launch")} if source.get("launch") else {}),
-            **({"label": source.get("label")} if source.get("label") else {}),
-            "auth": {
-                "status": "unknown",
-                "lastCheckedAt": None,
-                "lastAuthenticatedAt": None,
-                "lastLoggedOutAt": None,
-            },
         }
-        try:
-            shutil.copytree(source_root, temp_root)
-            if existing:
-                backup_root = tempfile.mkdtemp(prefix=f".{_encode(dest_name)}.backup.", dir=profiles_dir)
-                os.rmdir(backup_root)
-                if os.path.exists(dest_root):
-                    os.rename(dest_root, backup_root)
-            os.rename(temp_root, dest_root)
-            moved_temp = True
-            result = store["replace_session"](dest_name, replacement)
-            overwritten = bool(existing)
-        except Exception:
-            if moved_temp and os.path.exists(dest_root):
-                remove_tree(dest_root, ignore_errors=True)
-            if backup_root and os.path.exists(backup_root) and not os.path.exists(dest_root):
-                os.rename(backup_root, dest_root)
-            raise
-        finally:
-            if backup_root and os.path.exists(backup_root):
-                remove_tree(backup_root, ignore_errors=True)
-            remove_tree(temp_parent, ignore_errors=True)
-        if not result["ok"]:
-            raise CdxError(f"Failed to create session: {dest_name}")
-        return {"session": result["session"], "overwritten": overwritten}
-
-    def rename_session(source_name, dest_name):
-        if source_name == dest_name:
-            raise CdxError("Source and destination session names must be different")
-        _validate_new_session_name(dest_name)
-        source = store["get_session"](source_name)
-        if not source:
-            raise CdxError(f"Unknown session: {source_name}")
-        if store["get_session"](dest_name):
-            raise CdxError(f"Session already exists: {dest_name}")
 
-        source_root = source.get("sessionRoot") or _get_session_root(source_name)
-        dest_root = _get_session_root(dest_name)
-        if os.path.exists(dest_root):
-            raise CdxError(f"Session profile already exists: {dest_name}")
+    return store["update_session"](name, updater)
+
+def unset_launch_settings(store, name, keys):
+    session = store["get_session"](name)
+    if not session:
+        raise CdxError(f"Unknown session: {name}")
+    if not keys:
+        raise CdxError("At least one launch setting is required.")
+    allowed = {
+        "power", "reasoning_effort", "reasoningEffort", "permission", "fast", "rtk", "logics",
+        "model", "fallback_model", "budget", "extra_args", "priority",
+    }
+    unknown = [key for key in keys if key not in allowed]
+    if unknown:
+        raise CdxError(f"Unsupported launch setting: {', '.join(unknown)}")
+    now = _local_now_iso()
 
-        if os.path.exists(source_root):
-            os.rename(source_root, dest_root)
-            moved_profile = True
+    def updater(s):
+        current = dict(s.get("launch") or {})
+        for key in keys:
+            current.pop(key, None)
+        updated = {**s, "updatedAt": now}
+        if current:
+            updated["launch"] = current
         else:
-            moved_profile = False
+            updated.pop("launch", None)
+        return updated
 
-        now = _local_now_iso()
-        try:
-            result = store["rename_session"](source_name, dest_name, lambda s: {
-                **s,
-                "name": dest_name,
-                "sessionRoot": dest_root,
-                "authHome": _get_session_auth_home(dest_name, s["provider"]),
-                "updatedAt": now,
-            })
-        except Exception:
-            if moved_profile and os.path.exists(dest_root) and not os.path.exists(source_root):
-                os.rename(dest_root, source_root)
-            raise
-
-        if not result["ok"]:
-            if moved_profile and os.path.exists(dest_root) and not os.path.exists(source_root):
-                os.rename(dest_root, source_root)
-            if result["reason"] == "exists":
-                raise CdxError(f"Session already exists: {dest_name}")
-            raise CdxError(f"Unknown session: {source_name}")
-        return result["session"]
-
-    def launch_session(name):
-        session = store["get_session"](name)
-        if not session:
-            raise CdxError(f"Unknown session: {name}")
-        if session.get("enabled", True) is False:
-            raise CdxError(f"Session is disabled: {name}")
-        now = _local_now_iso()
-
-        def state_updater(state):
-            if not state:
-                raise CdxError(f"Session state missing for {name}. Reconnect required.")
-            return {**state, "rehydratedAt": now}
-
-        store["update_session_state"](name, state_updater)
-        return store["update_session"](name, lambda s: {
-            **s, "updatedAt": now, "lastLaunchedAt": now
-        })
+    return store["update_session"](name, updater)
 
-    def start_session_runtime(name, payload=None):
-        session = store["get_session"](name)
-        if not session:
-            raise CdxError(f"Unknown session: {name}")
-        payload = dict(payload or {})
-        now = _local_now_iso()
-        runtime = {
-            "status": "running",
-            "runId": payload.get("runId") or uuid.uuid4().hex,
-            "startedAt": payload.get("startedAt") or now,
-            "pid": payload.get("pid") or os.getpid(),
-            "command": payload.get("command"),
-            "label": payload.get("label"),
-            "transcriptPath": payload.get("transcript_path") or payload.get("transcriptPath"),
+def update_auth_state(store, name, updater):
+    now = _local_now_iso()
+    updated = store["update_session"](name, lambda s: {
+        **s,
+        "updatedAt": now,
+        "auth": updater(s.get("auth") or {}),
+    })
+    if not updated:
+        raise CdxError(f"Unknown session: {name}")
+    return updated
+
+
+def get_session(store, name):
+    return store["get_session"](name)
+
+
+def ensure_session_state(store, name):
+    session = store["get_session"](name)
+    if not session:
+        raise CdxError(f"Unknown session: {name}")
+    result = {}
+
+    def updater(state):
+        if state:
+            result["state"] = state
+            return None
+        repaired = {
+            "provider": session["provider"],
+            "status": "ready",
+            "rehydratedAt": None,
         }
+        result["state"] = repaired
+        return repaired
 
-        def updater(state):
-            if not state:
-                raise CdxError(f"Session state missing for {name}. Reconnect required.")
-            return {
-                **state,
-                "status": "running",
-                "runtime": runtime,
-            }
-
-        store["update_session_state"](name, updater)
-        return runtime
-
-    def finish_session_runtime(name, run_id=None, payload=None):
-        session = store["get_session"](name)
-        if not session:
-            raise CdxError(f"Unknown session: {name}")
-        payload = dict(payload or {})
-        outcome = {}
-
-        def updater(state):
-            if not state:
-                return None
-            runtime = state.get("runtime") or {}
-            if run_id and runtime.get("runId") != run_id:
-                outcome["runtime"] = runtime
-                return None
-            updated_runtime = {
-                **runtime,
-                "status": payload.get("status") or "stopped",
-                "endedAt": payload.get("endedAt") or _local_now_iso(),
-            }
-            if "returncode" in payload:
-                updated_runtime["returncode"] = payload["returncode"]
-            outcome["runtime"] = updated_runtime
-            return {
-                **state,
-                "status": "ready",
-                "runtime": updated_runtime,
-            }
-
-        store["update_session_state"](name, updater)
-        return outcome.get("runtime")
-
-    def ensure_session_state(name):
-        session = store["get_session"](name)
-        if not session:
-            raise CdxError(f"Unknown session: {name}")
-        result = {}
-
-        def updater(state):
-            if state:
-                result["state"] = state
-                return None
-            repaired = {
-                "provider": session["provider"],
-                "status": "ready",
-                "rehydratedAt": None,
-            }
-            result["state"] = repaired
-            return repaired
-
-        store["update_session_state"](name, updater)
-        return result["state"]
-
-    def list_sessions():
-        return store["list_sessions"]()
-
-    def get_session(name):
-        return store["get_session"](name)
-
-    def set_session_enabled(name, enabled):
-        session = store["get_session"](name)
-        if not session:
-            raise CdxError(f"Unknown session: {name}")
-        now = _local_now_iso()
-        return store["update_session"](name, lambda s: {
-            **s,
-            "enabled": bool(enabled),
-            "updatedAt": now,
-        })
+    store["update_session_state"](name, updater)
+    return result["state"]
 
-    def set_session_label(name, label):
-        session = store["get_session"](name)
-        if not session:
-            raise CdxError(f"Unknown session: {name}")
-        normalized = _normalize_session_label(label)
-        now = _local_now_iso()
-        return store["update_session"](name, lambda s: {
-            **s,
-            "label": normalized,
-            "updatedAt": now,
-        })
 
-    def clear_session_label(name):
-        session = store["get_session"](name)
-        if not session:
-            raise CdxError(f"Unknown session: {name}")
-        now = _local_now_iso()
-
-        def updater(s):
-            updated = {**s, "updatedAt": now}
-            updated.pop("label", None)
-            return updated
-
-        return store["update_session"](name, updater)
-
-    def set_launch_settings(name, settings):
-        session = store["get_session"](name)
-        if not session:
-            raise CdxError(f"Unknown session: {name}")
-        updates = _normalize_launch_settings(settings)
-        if not updates:
-            raise CdxError("At least one launch setting is required.")
-        now = _local_now_iso()
-
-        def updater(s):
-            # Build the new launch dict from the fresh record inside the store
-            # lock; a pre-lock snapshot loses a concurrent setting change.
-            current = _normalize_launch_settings(s.get("launch") or {}, mark_fast_service_tier=False)
-            launch = {**current, **updates}
-            if "power" in updates:
-                launch.pop("reasoning_effort", None)
-                launch.pop("reasoningEffort", None)
-            if "reasoning_effort" in updates:
-                launch.pop("power", None)
-            explicit_power = "power" in updates or "reasoning_effort" in updates
-            if explicit_power and "fast" not in updates and launch.get("fastMode") != "service_tier":
-                launch["fast"] = False
-                launch.pop("fastMode", None)
-            if updates.get("fast") is False:
-                launch.pop("fastMode", None)
-                if not any(key in launch for key in ("power", "reasoning_effort", "reasoningEffort")):
-                    launch["power"] = DEFAULT_LAUNCH_SETTINGS["power"]
-            return {
-                **s,
-                "launch": launch,
-                "updatedAt": now,
-            }
-
-        return store["update_session"](name, updater)
-
-    def unset_launch_settings(name, keys):
-        session = store["get_session"](name)
-        if not session:
-            raise CdxError(f"Unknown session: {name}")
-        if not keys:
-            raise CdxError("At least one launch setting is required.")
-        allowed = {"power", "reasoning_effort", "reasoningEffort", "permission", "fast", "rtk", "logics", "model", "priority"}
-        unknown = [key for key in keys if key not in allowed]
-        if unknown:
-            raise CdxError(f"Unsupported launch setting: {', '.join(unknown)}")
-        now = _local_now_iso()
-
-        def updater(s):
-            current = dict(s.get("launch") or {})
-            for key in keys:
-                current.pop(key, None)
-            updated = {**s, "updatedAt": now}
-            if current:
-                updated["launch"] = current
-            else:
-                updated.pop("launch", None)
-            return updated
+def set_session_label(store, name, label):
+    session = store["get_session"](name)
+    if not session:
+        raise CdxError(f"Unknown session: {name}")
+    normalized = _normalize_session_label(label)
+    now = _local_now_iso()
+    return store["update_session"](name, lambda s: {
+        **s,
+        "label": normalized,
+        "updatedAt": now,
+    })
 
-        return store["update_session"](name, updater)
 
-    def record_status(name, payload):
-        normalized = _normalize_status_payload(payload)
-        updated = store["update_session"](name, lambda s: {
-            **s,
-            "lastStatus": normalized,
-            "lastStatusAt": normalized["updated_at"],
-        })
-        if not updated:
-            raise CdxError(f"Unknown session: {name}")
+def clear_session_label(store, name):
+    session = store["get_session"](name)
+    if not session:
+        raise CdxError(f"Unknown session: {name}")
+    now = _local_now_iso()
+
+    def updater(s):
+        updated = {**s, "updatedAt": now}
+        updated.pop("label", None)
         return updated
 
-    def record_launch_history(name, payload):
-        session = store["get_session"](name)
-        if not session:
-            raise CdxError(f"Unknown session: {name}")
-        entry = {
-            "schema_version": 1,
-            "session_name": session["name"],
-            "provider": session["provider"],
-            "launch": session.get("launch") or {},
-            **payload,
-        }
-        store["append_launch_history"](entry)
-        return entry
-
-    def get_launch_history(name=None, limit=20):
-        if name and not store["get_session"](name):
-            raise CdxError(f"Unknown session: {name}")
-        return store["list_launch_history"](session_name=name, limit=limit)
-
-    def _resolve_session_status(
-        session,
-        force_refresh=False,
-        cache_ttl_seconds=STATUS_CACHE_TTL_SECONDS,
-        cache_only=False,
-        status_timeout_seconds=None,
-    ):
-        current_status = session.get("lastStatus")
-        if session.get("enabled", True) is False:
-            return current_status
-        if cache_only:
-            return current_status
-        if current_status and not force_refresh and _is_status_cache_fresh(session, ttl_seconds=cache_ttl_seconds):
-            return current_status
-        source_root = session.get("authHome") or _get_session_auth_home(
-            session["name"], session["provider"]
-        )
-        if session["provider"] == PROVIDER_CODEX and codex_status_fetcher:
-            live_status = _fetch_codex_status(
-                {**session, "authHome": source_root},
-                timeout_seconds=status_timeout_seconds,
-            )
-            if live_status:
-                record_status(session["name"], live_status)
-                return live_status
-
-        expected_account_email = (
-            _read_expected_account_email(source_root)
-            if session["provider"] == PROVIDER_CODEX
-            else None
-        )
-        artifact = find_latest_status_artifact(
-            source_root,
-            session["provider"],
-            expected_account_email=expected_account_email,
-        )
-        if (
-            session["provider"] == PROVIDER_CODEX
-            and not artifact
-            and os.path.abspath(base_dir) == os.path.abspath(get_cdx_home(env))
-        ):
-            global_root = _get_global_codex_home(env)
-            if global_root and os.path.abspath(global_root) != os.path.abspath(source_root):
-                artifact = find_latest_status_artifact(
-                    global_root,
-                    session["provider"],
-                    expected_account_email=expected_account_email,
-                    # The shared codex home can hold other accounts' rollouts;
-                    # structured payloads there cannot be attributed to ours.
-                    trust_unattributed_structured=False,
-                )
-        if not artifact:
-            if _is_low_confidence_status_source(current_status):
-                return None
-            return current_status
-        resolved = _normalize_status_payload({
-            "usage_pct": artifact.get("usage_pct"),
-            "remaining_5h_pct": artifact.get("remaining_5h_pct"),
-            "remaining_week_pct": artifact.get("remaining_week_pct"),
-            "credits": artifact.get("credits"),
-            "reset_5h_at": artifact.get("reset_5h_at"),
-            "reset_week_at": artifact.get("reset_week_at"),
-            "reset_at": artifact.get("reset_at"),
-            "updated_at": artifact.get("updated_at"),
-            "raw_status_text": artifact.get("raw_status_text"),
-            "source_ref": artifact.get("source_ref"),
-            "structured": artifact.get("structured"),
-        })
-        if _is_low_confidence_status_source(current_status) and not _is_low_confidence_status_source(resolved):
-            record_status(session["name"], resolved)
-            return resolved
-        if _is_status_newer(resolved, current_status):
-            record_status(session["name"], resolved)
-            return resolved
-        if _status_has_more_detail(resolved, current_status):
-            merged = _merge_status_payload(current_status, resolved)
-            record_status(session["name"], merged)
-            return merged
-        return current_status or resolved
-
-    def update_auth_state(name, updater):
-        now = _local_now_iso()
-        updated = store["update_session"](name, lambda s: {
+    return store["update_session"](name, updater)
+
+
+def set_session_enabled(store, name, enabled):
+    session = store["get_session"](name)
+    if not session:
+        raise CdxError(f"Unknown session: {name}")
+    now = _local_now_iso()
+    return store["update_session"](name, lambda s: {
+        **s,
+        "enabled": bool(enabled),
+        "updatedAt": now,
+    })
+
+
+def remove_session(base_dir, store, name):
+    session = store["get_session"](name)
+    if not session:
+        raise CdxError(f"Unknown session: {name}")
+    session_root = session.get("sessionRoot") or _get_session_root(base_dir, name)
+    quarantine_root = None
+    if os.path.exists(session_root):
+        profiles_dir = os.path.dirname(session_root)
+        os.makedirs(profiles_dir, exist_ok=True)
+        quarantine_root = tempfile.mkdtemp(prefix=f".{_encode(name)}.remove.", dir=profiles_dir)
+        os.rmdir(quarantine_root)
+        os.rename(session_root, quarantine_root)
+    try:
+        removed = store["remove_session"](name)
+    except Exception:
+        if quarantine_root and os.path.exists(quarantine_root) and not os.path.exists(session_root):
+            os.rename(quarantine_root, session_root)
+        raise
+    if not removed:
+        if quarantine_root and os.path.exists(quarantine_root) and not os.path.exists(session_root):
+            os.rename(quarantine_root, session_root)
+        raise CdxError(f"Unknown session: {name}")
+    if quarantine_root:
+        try:
+            remove_tree(quarantine_root)
+        except OSError as error:
+            raise CdxError(
+                f"Removed session {name}, but failed to delete archived profile {quarantine_root}: {error}"
+            ) from error
+    return removed
+
+
+def copy_session(base_dir, store, source_name, dest_name):
+    if source_name == dest_name:
+        raise CdxError("Source and destination session names must be different")
+    _validate_new_session_name(dest_name)
+    source = store["get_session"](source_name)
+    if not source:
+        raise CdxError(f"Unknown session: {source_name}")
+    existing = store["get_session"](dest_name)
+    overwritten = False
+    source_root = source.get("sessionRoot") or _get_session_root(base_dir, source_name)
+    dest_root = _get_session_root(base_dir, dest_name)
+    if not existing and os.path.exists(dest_root):
+        raise CdxError(f"Session profile already exists: {dest_name}")
+    dest_auth_home = _get_session_auth_home(base_dir, dest_name, source["provider"])
+    profiles_dir = os.path.dirname(dest_root)
+    os.makedirs(profiles_dir, exist_ok=True)
+    temp_parent = tempfile.mkdtemp(prefix=f".{_encode(dest_name)}.copy.", dir=profiles_dir)
+    temp_root = os.path.join(temp_parent, "profile")
+    backup_root = None
+    moved_temp = False
+    now = _local_now_iso()
+    replacement = {
+        "name": dest_name,
+        "provider": source["provider"],
+        "enabled": True,
+        "sessionRoot": dest_root,
+        "authHome": dest_auth_home,
+        "createdAt": now,
+        "updatedAt": now,
+        "lastLaunchedAt": None,
+        "lastStatusAt": None,
+        "lastStatus": None,
+        **({"launch": source.get("launch")} if source.get("launch") else {}),
+        **({"label": source.get("label")} if source.get("label") else {}),
+        "auth": {
+            "status": "unknown",
+            "lastCheckedAt": None,
+            "lastAuthenticatedAt": None,
+            "lastLoggedOutAt": None,
+        },
+    }
+    try:
+        shutil.copytree(source_root, temp_root)
+        if existing:
+            backup_root = tempfile.mkdtemp(prefix=f".{_encode(dest_name)}.backup.", dir=profiles_dir)
+            os.rmdir(backup_root)
+            if os.path.exists(dest_root):
+                os.rename(dest_root, backup_root)
+        os.rename(temp_root, dest_root)
+        moved_temp = True
+        result = store["replace_session"](dest_name, replacement)
+        overwritten = bool(existing)
+    except Exception:
+        if moved_temp and os.path.exists(dest_root):
+            remove_tree(dest_root, ignore_errors=True)
+        if backup_root and os.path.exists(backup_root) and not os.path.exists(dest_root):
+            os.rename(backup_root, dest_root)
+        raise
+    finally:
+        if backup_root and os.path.exists(backup_root):
+            remove_tree(backup_root, ignore_errors=True)
+        remove_tree(temp_parent, ignore_errors=True)
+    if not result["ok"]:
+        raise CdxError(f"Failed to create session: {dest_name}")
+    return {"session": result["session"], "overwritten": overwritten}
+
+
+def rename_session(base_dir, store, source_name, dest_name):
+    if source_name == dest_name:
+        raise CdxError("Source and destination session names must be different")
+    _validate_new_session_name(dest_name)
+    source = store["get_session"](source_name)
+    if not source:
+        raise CdxError(f"Unknown session: {source_name}")
+    if store["get_session"](dest_name):
+        raise CdxError(f"Session already exists: {dest_name}")
+
+    source_root = source.get("sessionRoot") or _get_session_root(base_dir, source_name)
+    dest_root = _get_session_root(base_dir, dest_name)
+    if os.path.exists(dest_root):
+        raise CdxError(f"Session profile already exists: {dest_name}")
+
+    if os.path.exists(source_root):
+        os.rename(source_root, dest_root)
+        moved_profile = True
+    else:
+        moved_profile = False
+
+    now = _local_now_iso()
+    try:
+        result = store["rename_session"](source_name, dest_name, lambda s: {
             **s,
+            "name": dest_name,
+            "sessionRoot": dest_root,
+            "authHome": _get_session_auth_home(base_dir, dest_name, s["provider"]),
             "updatedAt": now,
-            "auth": updater(s.get("auth") or {}),
         })
-        if not updated:
-            raise CdxError(f"Unknown session: {name}")
-        return updated
+    except Exception:
+        if moved_profile and os.path.exists(dest_root) and not os.path.exists(source_root):
+            os.rename(dest_root, source_root)
+        raise
+
+    if not result["ok"]:
+        if moved_profile and os.path.exists(dest_root) and not os.path.exists(source_root):
+            os.rename(dest_root, source_root)
+        if result["reason"] == "exists":
+            raise CdxError(f"Session already exists: {dest_name}")
+        raise CdxError(f"Unknown session: {source_name}")
+    return result["session"]
+
+
+def create_session(base_dir, env, store, name, provider=DEFAULT_PROVIDER):
+    _validate_new_session_name(name)
+    normalized_provider = _normalize_provider(provider)
+    session_root = _get_session_root(base_dir, name)
+    auth_home = _get_session_auth_home(base_dir, name, normalized_provider)
+    _ensure_private_dir(base_dir)
+    _ensure_private_dir(os.path.join(base_dir, "profiles"))
+    _ensure_private_dir(session_root)
+    _ensure_private_dir(auth_home)
+    if normalized_provider == PROVIDER_CODEX:
+        _seed_codex_auth_from_global(auth_home, env=env)
+    if normalized_provider == PROVIDER_CLAUDE:
+        _ensure_claude_attribution_disabled(auth_home)
+    now = _local_now_iso()
+    session = {
+        "name": name,
+        "provider": normalized_provider,
+        "enabled": True,
+        "sessionRoot": session_root,
+        "authHome": auth_home,
+        "createdAt": now,
+        "updatedAt": now,
+        "lastLaunchedAt": None,
+        "lastStatusAt": None,
+        "lastStatus": None,
+        "launch": dict(DEFAULT_LAUNCH_SETTINGS),
+        "auth": {
+            "status": "unknown",
+            "lastCheckedAt": None,
+            "lastAuthenticatedAt": None,
+            "lastLoggedOutAt": None,
+        },
+    }
+    result = store["add_session"](session)
+    if not result["ok"]:
+        raise CdxError(f"Session already exists: {name}")
+    return result["session"]
+
+
+def record_launch_history(store, name, payload):
+    session = store["get_session"](name)
+    if not session:
+        raise CdxError(f"Unknown session: {name}")
+    entry = {
+        "schema_version": 1,
+        "session_name": session["name"],
+        "provider": session["provider"],
+        "launch": session.get("launch") or {},
+        **payload,
+    }
+    store["append_launch_history"](entry)
+    _observe_codex_conversation(store, session)
+    return entry
 
-    def _status_cache_hit(s, force_refresh=False, cache_ttl_seconds=STATUS_CACHE_TTL_SECONDS, cache_only=False):
-        return (
-            cache_only
-            or s.get("enabled", True) is False
-            or (
-                s.get("lastStatus")
-                and not force_refresh
-                and _is_status_cache_fresh(s, ttl_seconds=cache_ttl_seconds)
-            )
-        )
-
-    def _resolve_row_session(
-        s,
-        force_refresh=False,
-        cache_ttl_seconds=STATUS_CACHE_TTL_SECONDS,
-        cache_only=False,
-        status_timeout_seconds=None,
-    ):
-        status = _resolve_session_status(
-            s,
-            force_refresh=force_refresh,
-            cache_ttl_seconds=cache_ttl_seconds,
-            cache_only=cache_only,
-            status_timeout_seconds=status_timeout_seconds,
-        )
-        return {
-            **s,
-            "lastStatus": status,
-            "lastStatusAt": (status and status.get("updated_at")) or s.get("lastStatusAt"),
-        }
 
-    def _status_row_from_session(s):
-        status = s.get("lastStatus")
-        enabled = s.get("enabled", True) is not False
-        row_status = status if enabled else None
+def _observe_codex_conversation(store, session):
+    """Read Codex's conversation id back after a run, if it wrote one.
+
+    Codex mints the id itself, so unlike Claude this can only be observed once
+    the rollout exists. Failing to find one is normal and leaves the session on
+    the recency resume path; it is never an error worth surfacing to a launch
+    that otherwise succeeded.
+    """
+    if session.get("provider") != PROVIDER_CODEX:
+        return
+    auth_home = session.get("authHome")
+    if not auth_home:
+        return
+    try:
+        identifier = find_latest_codex_conversation_id(auth_home)
+    except OSError:
+        return
+    if not identifier or identifier == (session.get("conversation") or {}).get("id"):
+        return
+    store["update_session"](session["name"], lambda s: {
+        **s,
+        "conversation": {
+            "id": identifier,
+            "provenance": "observed",
+            "recordedAt": _local_now_iso(),
+        },
+    })
+
+
+def get_launch_history(store, name=None, limit=20):
+    if name and not store["get_session"](name):
+        raise CdxError(f"Unknown session: {name}")
+    return store["list_launch_history"](session_name=name, limit=limit)
+
+
+def start_session_runtime(store, name, payload=None):
+    session = store["get_session"](name)
+    if not session:
+        raise CdxError(f"Unknown session: {name}")
+    payload = dict(payload or {})
+    now = _local_now_iso()
+    runtime = {
+        "status": "running",
+        "runId": payload.get("runId") or uuid.uuid4().hex,
+        "startedAt": payload.get("startedAt") or now,
+        "pid": payload.get("pid") or os.getpid(),
+        "command": payload.get("command"),
+        "label": payload.get("label"),
+        "transcriptPath": payload.get("transcript_path") or payload.get("transcriptPath"),
+    }
+
+    def updater(state):
+        if not state:
+            raise CdxError(f"Session state missing for {name}. Reconnect required.")
         return {
-            "session_name": s["name"],
-            "label": s.get("label"),
-            "provider": s["provider"],
-            "enabled": enabled,
-            "active": bool(_session_runtime(s["name"])) if enabled else False,
-            "status": "enabled" if enabled else "disabled",
-            "auth_status": (s.get("auth") or {}).get("status") or "unknown",
-            "auth_checked_at": _to_local_iso((s.get("auth") or {}).get("lastCheckedAt")),
-            "remaining_5h_pct": _normalize_pct_value(row_status.get("remaining_5h_pct")) if row_status else None,
-            "remaining_week_pct": _normalize_pct_value(row_status.get("remaining_week_pct")) if row_status else None,
-            "credits": row_status.get("credits") if row_status else None,
-            "reset_credits_available": row_status.get("reset_credits_available") if row_status else None,
-            "reset_credits": row_status.get("reset_credits") if row_status else None,
-            "available_pct": _compute_available_pct(row_status),
-            "reset_5h_at": row_status.get("reset_5h_at") if row_status else None,
-            "reset_week_at": row_status.get("reset_week_at") if row_status else None,
-            "reset_at": row_status.get("reset_at") if row_status else None,
-            "updated_at": _to_local_iso(s.get("lastStatusAt")),
-            "last_launched_at": _to_local_iso(s.get("lastLaunchedAt")),
+            **state,
+            "status": "running",
+            "runtime": runtime,
         }
 
-    def get_status_row(
-        name,
-        progress_callback=None,
-        force_refresh=False,
-        cache_ttl_seconds=STATUS_CACHE_TTL_SECONDS,
-        cache_only=False,
-        status_timeout_seconds=None,
-    ):
-        session = store["get_session"](name)
-        if not session:
-            raise CdxError(f"Unknown session: {name}")
-        cache_hit = _status_cache_hit(
-            session,
-            force_refresh=force_refresh,
-            cache_ttl_seconds=cache_ttl_seconds,
-            cache_only=cache_only,
-        )
-        if progress_callback:
-            progress_callback({
-                "event": "status_started",
-                "session_count": 1,
-                "check_count": 0 if cache_hit else 1,
-            })
-            if not cache_hit:
-                progress_callback({
-                    "event": "session_started",
-                    "session_name": session["name"],
-                    "provider": session["provider"],
-                })
-        resolved = _resolve_row_session(
-            session,
-            force_refresh=force_refresh,
-            cache_ttl_seconds=cache_ttl_seconds,
-            cache_only=cache_only,
-            status_timeout_seconds=status_timeout_seconds,
-        )
-        if progress_callback:
-            progress_callback({
-                "event": "session_finished",
-                "session_name": session["name"],
-                "has_status": bool(resolved.get("lastStatus")),
-                "cache_hit": cache_hit,
-            })
-            progress_callback({
-                "event": "status_finished",
-                "row_count": 1,
-            })
-        return _status_row_from_session(resolved)
-
-    def get_status_rows(
-        progress_callback=None,
-        force_refresh=False,
-        cache_ttl_seconds=STATUS_CACHE_TTL_SECONDS,
-        cache_only=False,
-        status_timeout_seconds=None,
-    ):
-        sessions = list_sessions()
-
-        cache_hits = {
-            s["name"]: _status_cache_hit(
-                s,
-                force_refresh=force_refresh,
-                cache_ttl_seconds=cache_ttl_seconds,
-                cache_only=cache_only,
-            )
-            for s in sessions
-        }
-        if progress_callback:
-            progress_callback({
-                "event": "status_started",
-                "session_count": len(sessions),
-                "check_count": sum(1 for cache_hit in cache_hits.values() if not cache_hit),
-            })
-
-        resolved_by_name = {}
-        if sessions:
-            max_workers = min(MAX_STATUS_WORKERS, len(sessions))
-            with ThreadPoolExecutor(max_workers=max_workers) as executor:
-                futures = {}
-                for s in sessions:
-                    cache_hit = cache_hits[s["name"]]
-                    if progress_callback and not cache_hit:
-                        progress_callback({
-                            "event": "session_started",
-                            "session_name": s["name"],
-                            "provider": s["provider"],
-                        })
-                    futures[executor.submit(
-                        _resolve_row_session,
-                        s,
-                        force_refresh=force_refresh,
-                        cache_ttl_seconds=cache_ttl_seconds,
-                        cache_only=cache_only,
-                        status_timeout_seconds=status_timeout_seconds,
-                    )] = s
-                for future in as_completed(futures):
-                    s = futures[future]
-                    try:
-                        resolved = future.result()
-                    except CdxError as error:
-                        if not str(error).startswith("Unknown session:"):
-                            raise
-                        continue
-                    resolved_by_name[s["name"]] = resolved
-                    if progress_callback:
-                        progress_callback({
-                            "event": "session_finished",
-                            "session_name": s["name"],
-                            "has_status": bool(resolved.get("lastStatus")),
-                            "cache_hit": cache_hits[s["name"]],
-                        })
-        resolved = [resolved_by_name[s["name"]] for s in sessions if s["name"] in resolved_by_name]
-
-        def sort_key(s):
-            at = s.get("lastStatusAt") or ""
-            disabled_rank = 1 if s.get("enabled", True) is False else 0
-            return (disabled_rank, "" if at else "\xff", at, s["name"])
-
-        resolved.sort(key=sort_key)
-        enabled = [s for s in resolved if s.get("enabled", True) is not False]
-        disabled = [s for s in resolved if s.get("enabled", True) is False]
-        enabled.reverse()
-        disabled.sort(key=lambda s: s["name"])
-        resolved = enabled + disabled
-
-        rows = []
-        for s in resolved:
-            rows.append(_status_row_from_session(s))
-        if progress_callback:
-            progress_callback({
-                "event": "status_finished",
-                "row_count": len(rows),
-            })
-        return rows
-
-    def format_list_rows():
-        sessions = list_sessions()
-        providers = {s["provider"] for s in sessions}
-        has_multiple = len(providers) > 1
-        sessions = sorted(
-            sessions,
-            key=lambda s: (
-                1 if s.get("enabled", True) is False else 0,
-                s.get("name", ""),
-            ),
-        )
-        return [{
-            "name": s["name"],
-            "label": s.get("label"),
-            "provider": s["provider"] if has_multiple else None,
-            "enabled": s.get("enabled", True) is not False,
-            "active": bool(_session_runtime(s["name"])) if s.get("enabled", True) is not False else False,
-            "enabled_status": "disabled" if s.get("enabled", True) is False else "enabled",
-            "status": s.get("lastStatus"),
-            "launch": s.get("launch") or {},
-            "updated_at": _to_local_iso(s.get("updatedAt")),
-        } for s in sessions]
-
-    def get_session_auth_home(name, provider):
-        return _get_session_auth_home(name, provider)
-
-    def get_session_root(name):
-        return _get_session_root(name)
-
-    def export_bundle(file_path, include_auth=False, session_names=None, passphrase=None, force=False, progress_callback=None):
-        if not file_path:
-            raise CdxError("Export path is required.")
-        if os.path.exists(file_path) and not force:
-            raise CdxError(f"Export path already exists: {file_path}")
-
-        sessions = _resolve_session_subset(session_names)
-        payload = {
-            "schema_version": 1,
-            "created_at": _local_now_iso(),
-            "include_auth": bool(include_auth),
-            "sessions": [],
-            "states": {},
-            "profiles": {},
+    store["update_session_state"](name, updater)
+    return runtime
+
+
+def finish_session_runtime(store, name, run_id=None, payload=None):
+    session = store["get_session"](name)
+    if not session:
+        raise CdxError(f"Unknown session: {name}")
+    payload = dict(payload or {})
+    outcome = {}
+
+    def updater(state):
+        if not state:
+            return None
+        runtime = state.get("runtime") or {}
+        if run_id and runtime.get("runId") != run_id:
+            outcome["runtime"] = runtime
+            return None
+        updated_runtime = {
+            **runtime,
+            "status": payload.get("status") or "stopped",
+            "endedAt": payload.get("endedAt") or _local_now_iso(),
         }
-        profile_file_count = 0
-        profile_bytes = 0
-        if progress_callback:
-            progress_callback({
-                "event": "export_started",
-                "include_auth": bool(include_auth),
-                "session_count": len(sessions),
-                "session_names": [session["name"] for session in sessions],
-            })
-        for session in sessions:
-            if progress_callback:
-                progress_callback({"event": "session_started", "session_name": session["name"]})
-            payload["sessions"].append(_build_export_session_record(session))
-            state = store["read_session_state"](session["name"])
-            if state is not None:
-                payload["states"][session["name"]] = state
-            if include_auth:
-                session_root = session.get("sessionRoot") or _get_session_root(session["name"])
-                profile = _collect_auth_files(session_root, session["provider"], session["name"], progress_callback)
-                payload["profiles"][session["name"]] = profile["files"]
-                profile_file_count += profile["file_count"]
-                profile_bytes += profile["bytes"]
-            if progress_callback:
-                progress_callback({"event": "session_finished", "session_name": session["name"]})
-
-        if progress_callback:
-            progress_callback({"event": "encoding_started"})
-        bundle_bytes = encode_bundle(payload, include_auth=include_auth, passphrase=passphrase)
-        if progress_callback:
-            progress_callback({"event": "writing_started", "path": file_path, "bundle_size_bytes": len(bundle_bytes)})
-        # Atomic + 0o600 from the start: the export path may live in a
-        # world-traversable directory, and a crash must not clobber a
-        # previous good bundle with a truncated one.
-        atomic_write(os.path.abspath(file_path), bundle_bytes, mode=0o600)
+        if "returncode" in payload:
+            updated_runtime["returncode"] = payload["returncode"]
+        outcome["runtime"] = updated_runtime
         return {
-            "path": file_path,
-            "include_auth": include_auth,
-            "session_names": [session["name"] for session in sessions],
-            "session_count": len(sessions),
-            "profile_file_count": profile_file_count if include_auth else None,
-            "profile_bytes": profile_bytes if include_auth else None,
-            "bundle_size_bytes": len(bundle_bytes),
+            **state,
+            "status": "ready",
+            "runtime": updated_runtime,
         }
 
-    def _validate_import_profile_files(payload, imported_sessions):
-        profiles = payload.get("profiles") or {}
-        if not isinstance(profiles, dict):
-            raise CdxError("Bundle contains invalid profile data.")
-        decoded_profiles = {}
-        for session_payload in imported_sessions:
-            name = session_payload["name"]
-            files = []
-            profile_items = profiles.get(name, [])
-            if not isinstance(profile_items, list):
-                raise CdxError(f"Bundle contains invalid profile data for session {name}.")
-            for item in profile_items:
-                if not isinstance(item, dict):
-                    raise CdxError(f"Bundle contains invalid profile entry for session {name}.")
-                rel_path = _safe_relpath(item.get("path"))
-                data_b64 = item.get("data_b64")
-                if not isinstance(data_b64, str):
-                    raise CdxError(f"Bundle contains invalid file data for session {name}: {rel_path}")
-                try:
-                    content = base64.b64decode(data_b64.encode("ascii"), validate=True)
-                except (binascii.Error, UnicodeEncodeError) as error:
-                    raise CdxError(f"Bundle contains invalid file data for session {name}: {rel_path}") from error
-                files.append({"path": rel_path, "content": content})
-            decoded_profiles[name] = files
-        return decoded_profiles
-
-    def _restore_import_backup(name, backup_root, session_root, old_record, old_state):
-        if os.path.exists(session_root):
-            remove_tree(session_root, ignore_errors=True)
-        if backup_root and os.path.exists(backup_root):
-            os.rename(backup_root, session_root)
-        if old_record:
-            store["replace_session"](name, old_record)
-            if old_state is not None:
-                store["write_session_state"](name, old_state)
-        else:
-            store["remove_session"](name)
-
-    def _force_import_preserved_profile_paths(session_root):
-        return [rel_path for rel_path in _FORCE_IMPORT_PRESERVED_PROFILE_PATHS if os.path.exists(os.path.join(session_root, rel_path))]
-
-    def _restore_force_import_profile_paths(name, backup_root, session_root, rel_paths):
-        if not backup_root:
-            return
-        for rel_path in rel_paths:
-            source_path = os.path.join(backup_root, rel_path)
-            dest_path = os.path.join(session_root, rel_path)
-            if not os.path.exists(source_path) or os.path.exists(dest_path):
-                continue
-            try:
-                if os.path.isdir(source_path) and not os.path.islink(source_path):
-                    shutil.copytree(source_path, dest_path)
-                else:
-                    _ensure_private_dir(os.path.dirname(dest_path))
-                    shutil.copy2(source_path, dest_path)
-            except Exception as error:
-                raise CdxError(f"Could not restore local plugin state for session {name}: {rel_path}") from error
-
-    def import_bundle(
-        file_path,
-        passphrase=None,
-        session_names=None,
-        force=False,
-        merge=False,
-        allow_authless_force=False,
-    ):
-        if not file_path or not os.path.isfile(file_path):
-            raise CdxError(f"Bundle file not found: {file_path}")
-        with open(file_path, "rb") as handle:
-            decoded = decode_bundle(handle.read(), passphrase=passphrase)
-        payload = decoded["payload"]
-        imported_sessions = payload.get("sessions") or []
-        if payload.get("schema_version") != 1:
-            raise CdxError("Unsupported bundle payload schema version.")
-
-        selected_names = set(session_names or [])
-        if selected_names:
-            imported_sessions = [item for item in imported_sessions if item["name"] in selected_names]
-            missing_names = sorted(selected_names - {item["name"] for item in imported_sessions})
-            if missing_names:
-                raise CdxError(f"Bundle does not contain requested sessions: {', '.join(missing_names)}")
-        names = [item["name"] for item in imported_sessions]
-
-        existing = {session["name"] for session in list_sessions()}
-        conflicts = [name for name in names if name in existing]
-        if conflicts and not force and not merge:
-            raise CdxError(f"Import would overwrite existing sessions: {', '.join(conflicts)}")
-        if conflicts and force and not decoded["meta"].get("include_auth") and not allow_authless_force:
-            raise CdxError(
-                "Import --force would overwrite existing session credentials, but this bundle has no auth payloads. "
-                "Re-export with --include-auth, use --merge, or pass --allow-authless-force to discard local credentials."
-            )
+    store["update_session_state"](name, updater)
+    return outcome.get("runtime")
 
-        for session_payload in imported_sessions:
-            _validate_new_session_name(session_payload["name"])
-            _normalize_provider(session_payload["provider"])
-        decoded_profiles = _validate_import_profile_files(payload, imported_sessions)
-
-        for session_payload in imported_sessions:
-            name = session_payload["name"]
-            provider = _normalize_provider(session_payload["provider"])
-            is_existing = name in existing
-
-            session_root = _get_session_root(name)
-            auth_home = _get_session_auth_home(name, provider)
-            _ensure_private_dir(base_dir)
-            _ensure_private_dir(os.path.join(base_dir, "profiles"))
-            backup_root = None
-            old_record = None
-            old_state = None
-            preserved_profile_paths = []
-            if is_existing and force:
-                old_record = store["get_session"](name)
-                old_state = store["read_session_state"](name)
-                preserved_profile_paths = _force_import_preserved_profile_paths(session_root)
-                if os.path.exists(session_root):
-                    backup_root = tempfile.mkdtemp(prefix=f".{_encode(name)}.import.", dir=os.path.dirname(session_root))
-                    os.rmdir(backup_root)
-                    os.rename(session_root, backup_root)
-                is_existing = False
-            _ensure_private_dir(session_root)
-            _ensure_private_dir(auth_home)
-
-            existing_state_before = None
-            try:
-                if is_existing and merge:
-                    existing_record = store["get_session"](name) or {}
-                    # replace_session resets the state file to defaults, so the
-                    # local state must be captured before it runs.
-                    existing_state_before = store["read_session_state"](name) or {}
-                    bundle_record = {
-                        **session_payload,
-                        "provider": provider,
-                        "enabled": session_payload.get("enabled", True) is not False,
-                        "sessionRoot": session_root,
-                        "authHome": auth_home,
-                    }
-                    # Existing values take precedence; bundle fills in missing keys only.
-                    merged_record = {**bundle_record, **{k: v for k, v in existing_record.items() if v is not None}}
-                    merged_record["sessionRoot"] = session_root
-                    merged_record["authHome"] = auth_home
-                    store["replace_session"](name, merged_record)
-                else:
-                    session_record = {
-                        **session_payload,
-                        "provider": provider,
-                        "enabled": session_payload.get("enabled", True) is not False,
-                        "sessionRoot": session_root,
-                        "authHome": auth_home,
-                    }
-                    store["replace_session"](name, session_record)
-
-                state = (payload.get("states") or {}).get(name)
-                if is_existing and merge:
-                    merged_state = {**(state or {}), **{k: v for k, v in (existing_state_before or {}).items() if v is not None}}
-                    if merged_state:
-                        store["write_session_state"](name, merged_state)
-                elif state is not None:
-                    store["write_session_state"](name, state)
-
-                for item in decoded_profiles.get(name, []):
-                    dest_path = os.path.join(session_root, item["path"])
-                    # In merge mode, skip files that already exist locally.
-                    if is_existing and merge and os.path.exists(dest_path):
-                        continue
-                    _ensure_private_dir(os.path.dirname(dest_path))
-                    # Decrypted credentials: 0o600 from creation, no umask window.
-                    atomic_write(dest_path, item["content"], mode=0o600)
-                _restore_force_import_profile_paths(name, backup_root, session_root, preserved_profile_paths)
-            except Exception:
-                _restore_import_backup(name, backup_root, session_root, old_record, old_state)
-                raise
-            finally:
-                if backup_root and os.path.exists(backup_root):
-                    remove_tree(backup_root, ignore_errors=True)
 
-        return {
-            "path": file_path,
-            "session_names": names,
-            "include_auth": bool(decoded["meta"].get("include_auth")),
-        }
+def launch_session(store, name):
+    session = store["get_session"](name)
+    if not session:
+        raise CdxError(f"Unknown session: {name}")
+    if session.get("enabled", True) is False:
+        raise CdxError(f"Session is disabled: {name}")
+    now = _local_now_iso()
+
+    def state_updater(state):
+        if not state:
+            raise CdxError(f"Session state missing for {name}. Reconnect required.")
+        return {**state, "rehydratedAt": now}
+
+    store["update_session_state"](name, state_updater)
+
+    def session_updater(s):
+        updated = {**s, "updatedAt": now, "lastLaunchedAt": now}
+        conversation = _conversation_identity_for_launch(s)
+        if conversation:
+            updated["conversation"] = conversation
+        return updated
+
+    return store["update_session"](name, session_updater)
+
+
+def _conversation_identity_for_launch(session):
+    """The conversation id this launch will carry, or None to leave it alone.
+
+    Claude accepts a caller-supplied `--session-id`, so cdx mints one here,
+    before the launch spec is built, and knows the conversation's identity
+    without having to find it afterwards. A fresh id per launch rather than one
+    reused forever: a launch starts a new conversation, and `cdx resume` should
+    mean the last one, so the stored value is always the newest. Reusing a
+    single id across launches would also depend on how the provider treats a
+    repeated `--session-id`, which is a behaviour cdx does not need to rely on.
+
+    Codex has no equivalent flag; its identity is read back from the rollout
+    after the run, so nothing is minted here.
+    """
+    if session.get("provider") != PROVIDER_CLAUDE:
+        return None
+    return {
+        "id": str(uuid.uuid4()),
+        "provenance": "imposed",
+        "recordedAt": _local_now_iso(),
+    }
+
+
+def begin_conversation(store, name):
+    """Mint the conversation id a Claude run is about to carry, and store it.
+
+    `launch_session` does this for interactive launches, but a headless run
+    never goes through it, so `cdx run` used to leave Claude sessions with no
+    identity at all - `cdx resume` then fell back to recency for Claude while
+    working by id for Codex, which records its own after the fact. Same shape
+    for both providers now: whatever ran last is what resume names.
+
+    Returns the updated session, or the unchanged one for providers that mint
+    nothing here.
+    """
+    session = store["get_session"](name)
+    if not session:
+        raise CdxError(f"Unknown session: {name}")
+    conversation = _conversation_identity_for_launch(session)
+    if not conversation:
+        return session
+    return store["update_session"](name, lambda s: {
+        **s, "conversation": conversation, "updatedAt": _local_now_iso(),
+    })
+
+
+def get_session_root(base_dir, name):
+    return _get_session_root(base_dir, name)
+
+
+def get_session_auth_home(base_dir, name, provider):
+    return _get_session_auth_home(base_dir, name, provider)
+
+
+def create_session_service(options=None):
+    if options is None:
+        options = {}
+    env = options.get("env", os.environ)
+    base_dir = options.get("base_dir") or get_cdx_home(env)
+    store = options.get("store") or create_session_store(base_dir)
+    custom_codex_status_fetcher = options.get("fetchCodexRateLimits")
+    codex_status_fetcher = custom_codex_status_fetcher or fetch_codex_rate_limits
+    default_status_timeout_seconds = (
+        _parse_status_timeout_seconds(options.get("statusTimeoutSeconds"))
+        or _parse_status_timeout_seconds(env.get("CDX_STATUS_TIMEOUT_SECONDS"))
+        or STATUS_PROBE_TIMEOUT_SECONDS
+    )
+
+    # None when there is no fetcher, so callers test the callable they were
+    # given rather than a separate flag they would also have to be passed.
+    fetch_codex_status = partial(
+        _fetch_codex_status,
+        codex_status_fetcher,
+        custom_codex_status_fetcher,
+        default_status_timeout_seconds,
+    ) if codex_status_fetcher else None
 
     return {
-        "create_session": create_session,
-        "remove_session": remove_session,
-        "copy_session": copy_session,
-        "rename_session": rename_session,
-        "launch_session": launch_session,
-        "active_session_runtime": _session_runtime,
-        "start_session_runtime": start_session_runtime,
-        "finish_session_runtime": finish_session_runtime,
-        "ensure_session_state": ensure_session_state,
-        "list_sessions": list_sessions,
-        "get_session": get_session,
-        "set_session_enabled": set_session_enabled,
-        "set_session_label": set_session_label,
-        "clear_session_label": clear_session_label,
-        "set_launch_settings": set_launch_settings,
-        "unset_launch_settings": unset_launch_settings,
-        "record_status": record_status,
-        "record_launch_history": record_launch_history,
-        "get_launch_history": get_launch_history,
-        "update_auth_state": update_auth_state,
-        "get_status_row": get_status_row,
-        "get_status_rows": get_status_rows,
-        "format_list_rows": format_list_rows,
-        "get_session_auth_home": get_session_auth_home,
-        "get_session_root": get_session_root,
-        "export_bundle": export_bundle,
-        "import_bundle": import_bundle,
+        "create_session": partial(create_session, base_dir, env, store),
+        "remove_session": partial(remove_session, base_dir, store),
+        "copy_session": partial(copy_session, base_dir, store),
+        "rename_session": partial(rename_session, base_dir, store),
+        "launch_session": partial(launch_session, store),
+        "begin_conversation": partial(begin_conversation, store),
+        "active_session_runtime": partial(_session_runtime, store),
+        "start_session_runtime": partial(start_session_runtime, store),
+        "finish_session_runtime": partial(finish_session_runtime, store),
+        "ensure_session_state": partial(ensure_session_state, store),
+        "list_sessions": partial(list_sessions, store),
+        "get_session": partial(get_session, store),
+        "set_session_enabled": partial(set_session_enabled, store),
+        "set_session_label": partial(set_session_label, store),
+        "clear_session_label": partial(clear_session_label, store),
+        "set_launch_settings": partial(set_launch_settings, store),
+        "unset_launch_settings": partial(unset_launch_settings, store),
+        "record_status": partial(record_status, store),
+        "record_launch_history": partial(record_launch_history, store),
+        "get_launch_history": partial(get_launch_history, store),
+        "update_auth_state": partial(update_auth_state, store),
+        "get_status_row": partial(get_status_row, store, base_dir, env, fetch_codex_status),
+        "get_status_rows": partial(get_status_rows, store, base_dir, env, fetch_codex_status),
+        "format_list_rows": partial(format_list_rows, store),
+        "get_session_auth_home": partial(get_session_auth_home, base_dir),
+        "get_session_root": partial(get_session_root, base_dir),
+        "export_bundle": partial(export_bundle, base_dir, store),
+        "import_bundle": partial(import_bundle, base_dir, store),
         "base_dir": base_dir,
         "normalize_provider": _normalize_provider,
     }