cdx-manager 0.21.6 → 0.23.0

package/src/session_backup.py

@@ -106,13 +106,16 @@ def _collect_auth_files(session_root, provider, session_name=None, progress_call
             })
     return {"files": files, "file_count": len(files), "bytes": total_bytes}
 
-def _validate_import_profile_files(payload, imported_sessions):
+def _validate_import_profile_files(payload, imported_sessions, include_auth=True):
     profiles = payload.get("profiles") or {}
     if not isinstance(profiles, dict):
         raise CdxError("Bundle contains invalid profile data.")
+    if any(profiles.values()) and not include_auth:
+        raise CdxError("Bundle contains profile files but no auth payload.")
     decoded_profiles = {}
     for session_payload in imported_sessions:
         name = session_payload["name"]
+        allowed_paths = _auth_bundle_paths(_normalize_provider(session_payload["provider"]))
         files = []
         profile_items = profiles.get(name, [])
         if not isinstance(profile_items, list):
@@ -121,6 +124,8 @@ def _validate_import_profile_files(payload, imported_sessions):
             if not isinstance(item, dict):
                 raise CdxError(f"Bundle contains invalid profile entry for session {name}.")
             rel_path = _safe_relpath(item.get("path"))
+            if rel_path not in allowed_paths:
+                raise CdxError(f"Bundle contains an unexpected file for session {name}: {rel_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}")
@@ -288,9 +293,14 @@ def import_bundle(base_dir, store, file_path,
         )
 
     for session_payload in imported_sessions:
-        _validate_new_session_name(session_payload["name"])
+        if session_payload["name"] not in existing:
+            _validate_new_session_name(session_payload["name"])
         _normalize_provider(session_payload["provider"])
-    decoded_profiles = _validate_import_profile_files(payload, imported_sessions)
+        # A rollback removes the profile folder, so never adopt one we did not create.
+        if session_payload["name"] not in existing and os.path.lexists(_get_session_root(base_dir, session_payload["name"])):
+            raise CdxError(f"Session profile already exists: {session_payload['name']}")
+    decoded_profiles = _validate_import_profile_files(payload, imported_sessions,
+                                                      include_auth=bool(decoded["meta"].get("include_auth")))
 
     for session_payload in imported_sessions:
         name = session_payload["name"]
@@ -318,7 +328,8 @@ def import_bundle(base_dir, store, file_path,
             bundle_carries_credential = provider == PROVIDER_CLAUDE and any(
                 item["path"] == CLAUDE_CREDENTIALS_BUNDLE_PATH for item in decoded_profiles.get(name, [])
             )
-            if bundle_carries_credential:
+            # Force replaces the login even when the bundle has none to offer.
+            if bundle_carries_credential or (force and provider == PROVIDER_CLAUDE):
                 local_credential = read_keychain_credentials(old_record["authHome"])
             recovery_dir = tempfile.mkdtemp(prefix=f".{_encode(name)}.import.", dir=os.path.dirname(session_root))
             backup_root = os.path.join(recovery_dir, "profile")
@@ -405,7 +416,7 @@ def import_bundle(base_dir, store, file_path,
                 # Decrypted credentials: 0o600 from creation, no umask window.
                 atomic_write(dest_path, item["content"], mode=0o600)
                 imported_paths.append(item["path"])
-            if provider == PROVIDER_CLAUDE and CLAUDE_CREDENTIALS_BUNDLE_PATH in imported_paths:
+            if provider == PROVIDER_CLAUDE and (force and old_record or CLAUDE_CREDENTIALS_BUNDLE_PATH in imported_paths):
                 delete_keychain_credentials(auth_home)
             _restore_force_import_profile_paths(name, backup_root, session_root, preserved_profile_paths)
         except Exception:

package/src/session_helpers.py

@@ -8,6 +8,7 @@ them there keep working.
 """
 
 import os
+import re
 import sys
 from datetime import datetime
 from urllib.parse import quote
@@ -150,6 +151,9 @@ def _validate_new_session_name(name):
         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")
+    # Tray launchers and shell hints pass the name to a shell: keep it inert.
+    if not re.fullmatch(r"[A-Za-z0-9][A-Za-z0-9._-]*", str(name)):
+        raise CdxError("Session name may only contain letters, digits, '.', '_' and '-', and must start with a letter or digit")
     if name in RESERVED_SESSION_NAMES:
         raise CdxError(f"Session name is reserved: {name}")
 

package/src/session_ranking.py

@@ -71,6 +71,8 @@ def reasoning_rank(value):
 
 
 def _is_usable_now(row):
+    if row.get("rate_limit_reached"):
+        return False
     available = row.get("available_pct")
     return available is not None and available > USABLE_AVAILABLE_THRESHOLD
 
@@ -164,6 +166,10 @@ def candidate_rows(rows, provider=None, require_ready=False, min_reasoning_effor
     for row in rows:
         if row.get("enabled", True) is False:
             continue
+        if row.get("policy") in ("ask-first", "never"):
+            # Never picked on the user's behalf: `ask-first` is still offered
+            # where a person confirms (cdx rescue), `never` is not offered at all.
+            continue
         if provider is not None and row.get("provider") != provider:
             continue
         if _row_is_logged_out(row):
@@ -199,6 +205,10 @@ def _row_is_ready(row):
 
 
 def _row_has_availability(row):
+    if row.get("rate_limit_reached"):
+        # The provider says this account cannot serve a task, whatever the
+        # percentage windows read.
+        return False
     available = row.get("available_pct")
     if available is None:
         # Unknown is not the same as empty. Excluding it here would make a

package/src/session_service.py

@@ -130,6 +130,7 @@ LAUNCH_REASONING_EFFORT_VALUES = REASONING_EFFORT_VALUES
 LAUNCH_PERMISSION_VALUES = PERMISSION_VALUES
 MAX_LAUNCH_MODEL_LENGTH = 128
 MIN_LAUNCH_PRIORITY = 0
+ACCOUNT_POLICIES = ("use", "ask-first", "never")
 MAX_LAUNCH_PRIORITY = 100
 DEFAULT_LAUNCH_SETTINGS = {
     "power": "medium",
@@ -147,7 +148,7 @@ def _seed_codex_auth_from_global(auth_home, env=None):
     return True
 
 
-_ON_OFF_SETTINGS = {"fast": "fast", "rtk": "rtk", "logics": "logics", "notify": "notify", "notify_preview": "notify preview", "scrub_env": "scrub env"}
+_ON_OFF_SETTINGS = {"fast": "fast", "rtk": "rtk", "logics": "logics", "notify": "notify", "notify_preview": "notify preview", "scrub_env": "scrub env", "shared_memory": "shared memory", "retro": "retro"}
 
 
 def _has_control_chars(text):
@@ -235,6 +236,10 @@ def _normalize_launch_settings(settings, mark_fast_service_tier=True):
         if priority < MIN_LAUNCH_PRIORITY or priority > MAX_LAUNCH_PRIORITY:
             raise CdxError(f"Unsupported priority: {settings['priority']}")
         normalized["priority"] = priority
+    if "policy" in settings and settings["policy"] is not None:
+        if settings["policy"] not in ACCOUNT_POLICIES:
+            raise CdxError(f"Unsupported policy: {settings['policy']} (use|ask-first|never)")
+        normalized["policy"] = settings["policy"]
     return normalized
 
 
@@ -319,7 +324,7 @@ def unset_launch_settings(store, name, keys):
         raise CdxError("At least one launch setting is required.")
     allowed = {
         "power", "reasoning_effort", "reasoningEffort", "permission", "fast", "rtk", "logics", "notify", "notify_preview",
-        "scrub_env", "model", "fallback_model", "budget", "extra_args", "priority",
+        "scrub_env", "shared_memory", "retro", "model", "fallback_model", "budget", "extra_args", "priority", "policy",
     }
     unknown = [key for key in keys if key not in allowed]
     if unknown:
@@ -626,6 +631,10 @@ 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)
+    if store["get_session"](name):
+        raise CdxError(f"Session already exists: {name}")
+    if os.path.lexists(session_root):
+        raise CdxError(f"Session profile already exists: {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"))
@@ -922,6 +931,16 @@ def begin_conversation(store, name):
     })
 
 
+def mark_conversation_rescued(store, name, conversation_id):
+    """Stamp the source of a rescue handoff so the same conversation is not handed off twice."""
+    def updater(s):
+        conversation = s.get("conversation") or {}
+        if conversation.get("id") != conversation_id:
+            return s
+        return {**s, "conversation": {**conversation, "rescuedAt": _local_now_iso()}}
+    return store["update_session"](name, updater)
+
+
 def get_session_root(base_dir, name):
     return _get_session_root(base_dir, name)
 
@@ -960,6 +979,7 @@ def create_session_service(options=None):
         "rename_session": partial(rename_session, base_dir, store),
         "launch_session": partial(launch_session, store),
         "begin_conversation": partial(begin_conversation, store),
+        "mark_conversation_rescued": partial(mark_conversation_rescued, store),
         "active_session_runtime": partial(_session_runtime, store),
         "start_session_runtime": partial(start_session_runtime, store),
         "finish_session_runtime": partial(finish_session_runtime, store),

package/src/session_status.py

@@ -7,7 +7,7 @@ coupling measurement supports. Moved verbatim; re-exported by session_service.
 import json
 import os
 from concurrent.futures import ThreadPoolExecutor, as_completed
-from datetime import datetime, timezone
+from datetime import datetime, timedelta, timezone
 
 from .claude_credentials import claude_auth_type, setup_token_days_left
 from .claude_usage import _decode_jwt_claims
@@ -41,6 +41,79 @@ def _to_local_iso(value):
         parsed = parsed.replace(tzinfo=timezone.utc)
     return parsed.astimezone().isoformat()
 
+_MONTHS = ("Jan", "Feb", "Mar", "Apr", "May", "Jun", "Jul", "Aug", "Sep", "Oct", "Nov", "Dec")
+
+
+def reset_iso(display, reference=None):
+    """`Oct 20 15:00` (local time, no year) as ISO 8601, or None.
+
+    Every status source stores resets in that display shape. The year is the
+    one that puts the reset closest to `reference` (when the status was read),
+    so a January reset read in late December lands in the next year. A reset
+    with no time of day stays a date.
+    """
+    parts = str(display or "").split()
+    if len(parts) not in (2, 3) or parts[0] not in _MONTHS or not parts[1].isdigit():
+        return None
+    try:
+        hour, minute = (int(v) for v in parts[2].split(":")) if len(parts) == 3 else (0, 0)
+        now = datetime.fromisoformat(str(reference)) if reference else datetime.now().astimezone()
+        if now.tzinfo is None:
+            now = now.astimezone()
+        month, day = _MONTHS.index(parts[0]) + 1, int(parts[1])
+        candidates = []
+        for year in (now.year - 1, now.year, now.year + 1):
+            try:
+                # Naive local time resolved by the system zone, so a reset on
+                # the other side of a DST change gets its own offset.
+                candidates.append(datetime(year, month, day, hour, minute).astimezone())
+            except (ValueError, OverflowError, OSError):
+                # Windows cannot place a time before 1970 in the local zone.
+                continue
+    except (TypeError, ValueError):
+        return None
+    if not candidates:
+        return None
+    best = min(candidates, key=lambda value: abs(value - now))
+    return best.date().isoformat() if len(parts) == 2 else best.isoformat()
+
+
+_WINDOWS = {"5h": timedelta(hours=5), "week": timedelta(days=7)}
+
+
+def runs_out_at(remaining_pct, reset_at_iso, window, read_at_iso):
+    """When the account empties at the pace it used since its window opened, or None.
+
+    The window opened `window` before its reset; what was used since then, over
+    the time elapsed at the reading, is the pace. None when that pace does not
+    empty the account before the window resets, or when a figure is missing.
+    """
+    try:
+        reset = datetime.fromisoformat(str(reset_at_iso))
+        read = datetime.fromisoformat(str(read_at_iso))
+        remaining = float(remaining_pct)
+    except (TypeError, ValueError):
+        return None
+    if reset.tzinfo is None or read.tzinfo is None or len(str(reset_at_iso)) <= 10:
+        return None
+    elapsed = (read - (reset - window)).total_seconds()
+    used = 100.0 - remaining
+    if remaining <= 0 or used <= 0 or elapsed <= 0:
+        return None
+    out = read + timedelta(seconds=remaining * elapsed / used)
+    return out.isoformat() if out < reset else None
+
+
+def _runs_out(row):
+    """The earlier of the two windows' run-out times."""
+    times = [
+        runs_out_at(row.get(f"remaining_{name}_pct"), row.get(f"reset_{name}_at_iso"), window, row.get("updated_at"))
+        for name, window in _WINDOWS.items()
+    ]
+    times = [value for value in times if value]
+    return min(times, key=datetime.fromisoformat) if times else None
+
+
 def _row_priority(session):
     launch = session.get("launch") or {}
     try:
@@ -265,13 +338,32 @@ def _fetch_codex_status(codex_status_fetcher, custom_codex_status_fetcher, defau
     timeout = timeout_seconds or default_status_timeout_seconds
     return codex_status_fetcher(session, timeout=timeout)
 
+def session_paths(session):
+    """Where a session's files live, so a caller never rebuilds cdx's layout.
+
+    `profile_dir` is the session's own directory and `transcripts_dir` the
+    provider's conversation store inside it (None for a provider cdx does not
+    read transcripts from). The credential home itself is deliberately not
+    named, the same rule `cdx status` rows follow.
+    """
+    auth_home = session.get("authHome")
+    transcripts = {
+        PROVIDER_CLAUDE: (".claude", "projects"),
+        PROVIDER_CODEX: ("sessions",),
+    }.get(session.get("provider"))
+    return {
+        "profile_dir": session.get("sessionRoot") or auth_home,
+        "transcripts_dir": os.path.join(auth_home, *transcripts) if auth_home and transcripts else None,
+    }
+
+
 def _status_row_from_session(store, s):
     status = s.get("lastStatus")
     enabled = s.get("enabled", True) is not False
     row_status = status if enabled else None
     runtime = _session_runtime(store, s["name"])
     auth_type = claude_auth_type(s["authHome"]) if s["provider"] == PROVIDER_CLAUDE and s.get("authHome") else None
-    return {
+    row = {
         "session_name": s["name"],
         "label": s.get("label"),
         "provider": s["provider"],
@@ -281,6 +373,7 @@ def _status_row_from_session(store, s):
         # recommendation path could not see either, which is why `cdx next`
         # ignored `--priority` entirely.
         "priority": _row_priority(s),
+        "policy": (s.get("launch") or {}).get("policy") or "use",
         "reasoning_effort": _row_reasoning_effort(s),
         "active": bool(runtime) if enabled else False,
         "cwd": runtime.get("cwd") if runtime else None,
@@ -298,9 +391,18 @@ def _status_row_from_session(store, s):
         "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,
+        # The provider's typed block reason (workspace_owner_credits_depleted):
+        # failover and ranking read it, since the percentages can look healthy.
+        "rate_limit_reached": row_status.get("rate_limit_reached") if row_status else None,
+        **{
+            f"{key}_iso": reset_iso(row_status.get(key), _to_local_iso(s.get("lastStatusAt"))) if row_status else None
+            for key in ("reset_5h_at", "reset_week_at", "reset_at")
+        },
         "updated_at": _to_local_iso(s.get("lastStatusAt")),
         "last_launched_at": _to_local_iso(s.get("lastLaunchedAt")),
     }
+    row["runs_out_at_iso"] = _runs_out(row)
+    return row
 
 def format_list_rows(store):
     sessions = list_sessions(store)
@@ -387,6 +489,7 @@ def _resolve_session_status(store, base_dir, env, fetch_codex_status, session,
         "reset_5h_at": artifact.get("reset_5h_at"),
         "reset_week_at": artifact.get("reset_week_at"),
         "reset_at": artifact.get("reset_at"),
+        "rate_limit_reached": artifact.get("rate_limit_reached"),
         "updated_at": artifact.get("updated_at"),
         "raw_status_text": artifact.get("raw_status_text"),
         "source_ref": artifact.get("source_ref"),

package/src/shared_memory.py

@@ -0,0 +1,102 @@
+"""One Claude auto-memory per project, shared by the profiles that opt in.
+
+Claude Code keeps its auto-memory under the profile home
+(`.claude/projects/<project>/memory`), and cdx gives every profile its own
+home, so a fact learned on one account is unknown on the next. A profile with
+`shared_memory` on gets that directory as a symlink into
+`<cdx home>/shared-memory/<project>`, which every such profile reads and
+writes.
+
+Nothing is ever deleted. A profile's existing memory is copied into the store
+and the original directory kept beside it as `memory.pre-cdx-<time>`. Two
+files with the same name and different content are a conflict: the profile
+is left as it was and the caller says which files to merge by hand. The
+`MEMORY.md` index is the one exception, since it is one line per memory: its
+lines are merged, store first.
+"""
+
+import filecmp
+import os
+import re
+import shutil
+import time
+
+INDEX_NAME = "MEMORY.md"
+#: Claude Code shortens longer project folder names with a hash cdx cannot
+#: reproduce, so those projects are left alone rather than guessed at.
+MAX_PROJECT_NAME = 200
+
+
+def claude_project_name(cwd):
+    """The folder name Claude Code files a working directory under."""
+    return re.sub(r"[^A-Za-z0-9]", "-", os.path.realpath(cwd))
+
+
+def store_dir(base_dir, project):
+    return os.path.join(base_dir, "shared-memory", project)
+
+
+def link(auth_home, base_dir, cwd, now=None):
+    """Point the profile's memory for `cwd` at the shared store.
+
+    Returns (status, detail): `linked` (done now or already), `skipped`
+    (project name too long, or the memory path is a link cdx did not make),
+    `conflict` (detail lists the files), `unsupported` (no symlinks here).
+    """
+    project = claude_project_name(cwd)
+    if len(project) > MAX_PROJECT_NAME:
+        return "skipped", "project path too long to match Claude Code's folder name"
+    store = store_dir(base_dir, project)
+    memory = os.path.join(auth_home, ".claude", "projects", project, "memory")
+    if os.path.islink(memory):
+        if os.path.realpath(memory) == os.path.realpath(store):
+            return "linked", memory
+        return "skipped", f"{memory} already links elsewhere"
+    os.makedirs(store, exist_ok=True)
+    if os.path.isdir(memory):
+        conflicts = _conflicts(memory, store)
+        if conflicts:
+            return "conflict", conflicts
+        _merge_into(memory, store)
+        stamp = time.strftime("%Y%m%dT%H%M%S", time.gmtime(time.time() if now is None else now))
+        os.rename(memory, f"{memory}.pre-cdx-{stamp}")
+    else:
+        os.makedirs(os.path.dirname(memory), exist_ok=True)
+    try:
+        os.symlink(store, memory, target_is_directory=True)
+    except (OSError, NotImplementedError) as error:
+        return "unsupported", str(error)
+    return "linked", memory
+
+
+def _conflicts(memory, store):
+    found = []
+    for name in sorted(os.listdir(memory)):
+        source, target = os.path.join(memory, name), os.path.join(store, name)
+        if not os.path.exists(target) or name == INDEX_NAME:
+            continue
+        if os.path.isdir(source) or os.path.isdir(target) or not filecmp.cmp(source, target, shallow=False):
+            found.append(name)
+    return found
+
+
+def _merge_into(memory, store):
+    for name in os.listdir(memory):
+        source, target = os.path.join(memory, name), os.path.join(store, name)
+        if name == INDEX_NAME and os.path.exists(target):
+            _merge_index(source, target)
+        elif not os.path.exists(target):
+            if os.path.isdir(source):
+                shutil.copytree(source, target)
+            else:
+                shutil.copy2(source, target)
+
+
+def _merge_index(source, target):
+    with open(target, encoding="utf-8") as handle:
+        kept = handle.read().splitlines()
+    with open(source, encoding="utf-8") as handle:
+        added = [line for line in handle.read().splitlines() if line.strip() and line not in kept]
+    if added:
+        with open(target, "w", encoding="utf-8") as handle:
+            handle.write("\n".join(kept + added) + "\n")

package/src/status_source.py

@@ -773,6 +773,8 @@ def find_latest_status_artifact(
                 "reset_5h_at": candidate["structured"].get("reset_5h_at"),
                 "reset_week_at": candidate["structured"].get("reset_week_at"),
                 "reset_at": candidate["structured"].get("reset_at"),
+                # Never backfilled from an older record: null means not blocked.
+                "rate_limit_reached": candidate["structured"].get("rate_limit_reached"),
                 "raw_status_text": candidate["structured"].get("raw_status_text"),
                 "_skip_5h_backfill": candidate["structured"].get("_skip_5h_backfill"),
             }

package/src/status_view.py

@@ -1,4 +1,4 @@
-from datetime import datetime, timedelta
+from datetime import datetime
 from decimal import ROUND_HALF_UP, Decimal, InvalidOperation
 
 from .cli_render import (
@@ -10,6 +10,7 @@ from .cli_render import (
     _style_pct,
 )
 from .session_ranking import rank_sessions
+from .session_status import reset_iso
 
 RESET_COUNTDOWN_SAFETY_SECONDS = 60
 PRIORITY_EMPTY_AVAILABLE_THRESHOLD = 5
@@ -339,32 +340,21 @@ def _parse_reset_timestamp(value):
     if not value:
         return None
     text = str(value).strip()
+    # A year-less display ("Dec 31 23:00") becomes ISO first: reset_iso picks
+    # the year closest to now and the offset valid on that date, so neither a
+    # new-year wrap nor a DST change shifts the reset.
+    display = reset_iso(text)
+    if display is not None:
+        if "T" not in display:
+            return None  # a reset with no time of day has no countdown
+        text = display
     try:
         parsed = datetime.fromisoformat(text.replace("Z", "+00:00"))
-        if parsed.tzinfo is None:
-            parsed = parsed.replace(tzinfo=datetime.now().astimezone().tzinfo)
-        return parsed.timestamp()
     except (TypeError, ValueError):
-        pass
-    now = datetime.now().astimezone()
-    parsed = None
-    # Parse with an explicit year: strptime's implicit 1900 rejects "Feb 29",
-    # and the current year may not hold the date at all around new year.
-    for year in (now.year, now.year + 1):
-        try:
-            parsed = datetime.strptime(f"{year} {text}", "%Y %b %d %H:%M").replace(tzinfo=now.tzinfo)
-            break
-        except (TypeError, ValueError):
-            continue
-    if parsed is None:
         return None
-    # A year-less date nearly a year in the past is a year wrap ("Jan 2"
-    # rendered on Dec 31), not a reset that passed months ago.
-    if parsed < now - timedelta(days=182):
-        try:
-            parsed = parsed.replace(year=parsed.year + 1)
-        except ValueError:
-            pass
+    if parsed.tzinfo is None:
+        # Naive means local; astimezone() resolves the offset for that date.
+        parsed = parsed.astimezone()
     return parsed.timestamp()
 
 
@@ -390,11 +380,21 @@ def _format_status_detail(row, use_color=False):
         f"{_style('Reset expiry:', '1', use_color)} {_style_reset_time(_nearest_reset_expiry(row), use_color)}",
         f"{_style('5h reset:', '1', use_color)} {_style_reset_time(row.get('reset_5h_at'), use_color)}",
         f"{_style('Week reset:', '1', use_color)} {_style_reset_time(row.get('reset_week_at'), use_color)}",
+        *([f"{_style('Runs out:', '1', use_color)} {_style(_format_runs_out(row['runs_out_at_iso']), '33', use_color)}"] if row.get("runs_out_at_iso") else []),
         f"{_style('Updated:', '1', use_color)} {_dim(_format_relative_age(row.get('updated_at')), use_color)}",
     ]
     return "\n".join(lines)
 
 
+def _format_runs_out(iso):
+    """`~16:20 at this pace` (or with the date when it is not today)."""
+    from datetime import datetime
+
+    when = datetime.fromisoformat(iso).astimezone()
+    stamp = when.strftime("%H:%M") if when.date() == datetime.now().astimezone().date() else when.strftime("%b %d %H:%M")
+    return f"~{stamp} at this pace"
+
+
 def _nearest_reset_expiry(row):
     values = [credit.get("expires_at") for credit in row.get("reset_credits") or [] if credit.get("expires_at")]
     return min(values, key=lambda value: _parse_reset_timestamp(value) or float("inf")) if values else None

package/src/tray_autostart.py

@@ -18,8 +18,27 @@ RUN_KEY = r"HKCU\Software\Microsoft\Windows\CurrentVersion\Run"
 RUN_VALUE = "CDXTray"
 
 
+def _operator_home():
+    """The operator's real home from passwd. Inside a cdx session HOME is the
+    profile home, where launchd and the XDG autostart never look."""
+    try:
+        import pwd
+
+        return pwd.getpwuid(os.getuid()).pw_dir
+    except (ImportError, KeyError):
+        return None
+
+
 def _home(env):
-    return env.get("HOME") or os.path.expanduser("~")
+    return _operator_home() or env.get("HOME") or os.path.expanduser("~")
+
+
+def _desktop_exec(executable):
+    """Quote one argument per the desktop-entry spec: backslash-escape the four
+    reserved characters inside double quotes, then apply the string-value escape
+    to backslashes, and double `%` so it is not read as a field code."""
+    quoted = "".join("\\" + c if c in '"`$\\' else c for c in executable)
+    return '"' + quoted.replace("\\", "\\\\").replace("%", "%%") + '"'
 
 
 def artifact_path(env=None, system=None):
@@ -86,7 +105,7 @@ def enable(executable, env=None, system=None, run=None):
         with open(path, "w", encoding="utf-8") as handle:
             handle.write(
                 "[Desktop Entry]\nType=Application\nName=CDX Tray\n"
-                f"Exec={executable}\nX-GNOME-Autostart-enabled=true\n"
+                f"Exec={_desktop_exec(executable)}\nX-GNOME-Autostart-enabled=true\n"
             )
     return path
 

package/src/tray_instance.py

@@ -2,7 +2,9 @@
 
 The companion owns the lock; this only reads it. Both sides must agree on the
 path, which is why the rule is written in one sentence in both places: the
-per-user temporary directory, then `cdx-tray/companion.pid`.
+per-user directory (LOCALAPPDATA on Windows, TMPDIR on macOS, XDG_RUNTIME_DIR on
+Linux, else the temp dir with the uid in the folder name), then
+`cdx-tray/companion.pid`.
 """
 import os
 import platform
@@ -13,8 +15,15 @@ from .session_helpers import _process_is_running
 
 def lock_path(env=None):
     env = os.environ if env is None else env
-    if platform.system() == "Windows":
+    system = platform.system()
+    if system == "Windows":
         base = env.get("LOCALAPPDATA") or tempfile.gettempdir()
+    elif system == "Linux":
+        # /tmp is shared on Linux: one user's lock would block another's tray.
+        if env.get("XDG_RUNTIME_DIR"):
+            return os.path.join(env["XDG_RUNTIME_DIR"], "cdx-tray", "companion.pid")
+        base = env.get("TMPDIR") or tempfile.gettempdir()
+        return os.path.join(base, f"cdx-tray-{os.getuid()}", "companion.pid")
     else:
         base = env.get("TMPDIR") or tempfile.gettempdir()
     return os.path.join(base, "cdx-tray", "companion.pid")

package/src/update_manager.py

@@ -140,11 +140,14 @@ def _build_python_step(target_version):
     }
 
 
-def _build_npm_step(target_version):
+def _build_npm_step(target_version, env=None):
     spec = f"cdx-manager@{target_version}" if target_version else "cdx-manager@latest"
+    # Resolved here because Windows ships npm as npm.cmd, which a shell-less
+    # spawn of "npm" never finds.
+    npm = shutil.which("npm", path=(env or os.environ).get("PATH")) or "npm"
     return {
         "label": "npm global upgrade",
-        "command": ["npm", "install", "-g", spec],
+        "command": [npm, "install", "-g", spec],
         "cwd": None,
         "env": {},
     }
@@ -162,7 +165,7 @@ def build_update_plan(target_version=None, package_root=None, env=None, prefix=N
     elif mode == "python":
         steps = [_build_python_step(version)]
     elif mode == "npm":
-        steps = [_build_npm_step(version)]
+        steps = [_build_npm_step(version, env)]
     else:
         raise CdxError(
             "Unable to determine how cdx-manager was installed. "
@@ -195,7 +198,10 @@ def run_update_plan(plan, runner=None, env=None):
     for step in plan["steps"]:
         step_env = {**(env or os.environ), **(step.get("env") or {})}
         kwargs = {"cwd": step.get("cwd"), "env": step_env, "check": False}
-        result = runner(step["command"], **kwargs)
+        try:
+            result = runner(step["command"], **kwargs)
+        except OSError as error:
+            result = {"returncode": None, "stdout": "", "stderr": f"could not run {step['command'][0]}: {error}"}
         code = _result_code(result)
         results.append({
             "label": step["label"],