cdx-manager 0.20.8 → 0.20.10

package/README.md

@@ -4,7 +4,7 @@
 
 <br clear="left"/>
 
-[![License](https://img.shields.io/badge/license-MIT-4C8BF5)](LICENSE) ![Version](https://img.shields.io/badge/version-v0.20.8-4C8BF5) ![Python](https://img.shields.io/badge/python-3.9%2B-3776AB?logo=python&logoColor=white)
+[![License](https://img.shields.io/badge/license-MIT-4C8BF5)](LICENSE) ![Version](https://img.shields.io/badge/version-v0.20.10-4C8BF5) ![Python](https://img.shields.io/badge/python-3.9%2B-3776AB?logo=python&logoColor=white)
 
 **Stop guessing which AI account still has quota.** `cdx` tracks the rate-limit window of every Codex and Claude account you own, tells you which one is usable right now, and launches it with isolated auth — in one command.
 
@@ -128,6 +128,7 @@ The reason `cdx` exists: knowing, across every account you own, which one you ca
 - Environment isolation per session:
   - Codex sessions override `CODEX_HOME` to a dedicated profile directory.
   - Claude sessions override `HOME` to a dedicated profile directory and disable Claude Code commit co-author attribution by default.
+  - On macOS, Claude credentials use a profile-specific keychain entry. Quota refresh reads that entry before legacy credential files; `cdx cp` and `cdx ren` transfer only the profile's entry, never the system keychain directory. Rename refuses existing destination entries and reports any old-entry cleanup failure after the new session becomes usable; `cdx rm` deletes the profile's entry with the profile.
   - Antigravity sessions launch `agy` with a dedicated `HOME` for file-based settings; Google account credentials may still be stored in the OS keyring by Antigravity itself.
   - Ollama sessions use the local Ollama server and launch `ollama run <model>`; set a model with `cdx set <name> --model <model>`.
   - New Codex sessions seed their auth home from your existing global `~/.codex/auth.json` when available, so an already logged-in Codex CLI can be reused without giving up per-session isolation afterward.
@@ -910,6 +911,8 @@ cdx import backup-auth.cdx --passphrase-env CDX_BUNDLE_PASSPHRASE
 Notes:
 
 - `--include-auth` is encrypted, requires a passphrase, and exports only provider credential files rather than full profile caches, logs, or installed plugins.
+- Keychain-backed Claude authentication cannot currently be exported. If any selected profile uses it, `--include-auth` exits non-zero before writing anything, including with `--force`; text and JSON errors identify the affected profiles. Export without `--include-auth` and log in after import, or select only profiles whose authentication is file-backed. An inaccessible keychain is an explicit error, not a successful incomplete export.
+- Merge imports snapshot each existing profile before modification, preserving symlinks instead of following them. This temporarily needs space for a second copy of that profile. On failure, CDX restores the original files, record and state; if recovery also fails, the error gives the retained recovery directory containing the original metadata and any remaining profile snapshot.
 - Without `--passphrase-env`, `cdx` prompts in an interactive terminal. Non-interactive callers can pass `--passphrase-stdin` to read the passphrase from stdin (one line) instead of exposing it in the child environment.
 - `--sessions work,perso` exports or imports only a subset.
 - `--force` allows overwriting existing destination sessions during import or replacing an existing bundle file during export. Import preserves detected local `plugins/` state when the bundle does not provide it, and refuses to overwrite existing sessions from a bundle without auth payloads unless `--allow-authless-force` is also passed.

package/VERSION

@@ -1 +1 @@
-0.20.8
+0.20.10

package/changelogs/CHANGELOGS_0_20_10.md

@@ -0,0 +1,71 @@
+# CDX Manager 0.20.10
+
+## Fixes
+
+- Keep the local account when `cdx import --merge` brings in a bundle that
+  carries authentication. A keychain-backed profile has no credential file, so
+  the collision was never noticed and the local login was replaced and its
+  keychain entry deleted by an operation whose whole promise is to keep local
+  values. The collision is now resolved against the keychain itself, and the
+  import says which sessions kept their existing Claude authentication.
+- Restore the destination's Claude credential when `cdx import --force` fails
+  after staging the imported one. Filesystem rollback already worked; the
+  keychain entry did not come back, which lost the profile's only login. It is
+  snapshotted before anything can clear it and restored on failure, and a
+  recovery that cannot complete now names Claude keychain authentication
+  instead of reporting a generic incomplete recovery.
+- Decode encrypted bundles with the key derivation function their exporter
+  recorded. A bundle written on a Python without `hashlib.scrypt` stopped
+  opening on a Python that has it, with the same passphrase, because decoding
+  re-chose the derivation from the importing runtime. A derivation this runtime
+  cannot compute is now reported as such rather than as a wrong passphrase, and
+  older bundles that recorded nothing usable stay readable.
+- Keep every accepted note when several agents append to the same `cdx memory`
+  scope at once. The append read the scope and wrote it back with nothing
+  covering the pair, so both callers were told their note was accepted and one
+  of them was not there.
+- Make `cdx run --detach` actually run. The child was asked for a CLI module
+  that does not exist, so the launcher reported a run id for work that never
+  started and never cleaned up its staged prompt. A module name that does not
+  resolve now fails the launch instead of being reported as launched.
+- Terminate the provider when a headless run is interrupted. Ctrl-C unwound the
+  supervising CLI and left the provider running in its own process group, still
+  consuming quota and writing to the working tree, while the run record
+  described the supervisor. The provider tree is now terminated and reaped, and
+  the run is recorded as `cancelled` with exit code 130, which a caller can tell
+  apart from a failure and from a timeout.
+- Keep a working tray when replacing the companion fails midway. A filesystem
+  error between retiring the installed companion and promoting the staged one
+  left the install record pointing at a path with nothing in it, and skipped the
+  restart of the tray that had just been stopped. The proven companion is put
+  back and the tray is restarted on it.
+- Keep the Windows Start Menu shortcut pointing at the companion that is
+  actually installed. It was written against the staged executable, which the
+  update then moved, and the promoted install record dropped it, so uninstall
+  stopped removing it. It is now written by the promotion against the final
+  path and stays owned by uninstall.
+- Make the macOS pre-promotion launch check real. `--print` was handed to the
+  `open` utility rather than to the companion and the exit status was ignored,
+  so the gate passed for an app bundle that never started. It now runs the
+  binary inside the bundle, refuses a bundle with nothing runnable in it, and
+  still accepts a companion that started and reported a problem of its own.
+- Open the intended command when a Windows tray reaches CDX through WSL.
+  A session's launch settings row sent `config <session>` as a single argument,
+  so CDX saw one session name with a space in it and refused it.
+- Offer only terminals a Windows tray can open. The candidate list is built by
+  whichever host answers the poll, which under WSL is Linux, so the menu could
+  offer a Linux terminal and then open nothing when it was chosen. The
+  companion now lists what it can launch, and a stored preference it cannot
+  open falls back to the default console instead of an inert click.
+- Run the selected command when the tray terminal preference is `cmd`. It was
+  given PowerShell's `-NoExit -Command`, which `cmd.exe` accepts without
+  running anything, so the click opened an idle shell.
+
+## Notes
+
+- A cancelled headless run is a new terminal state: `cancelled`, alongside
+  `succeeded`, `failed` and `timed_out`. Callers that branch on run status
+  should treat it as an outcome rather than as an unknown value.
+- Bundles exported by this version record and honour their key derivation
+  function. Bundles exported by earlier versions are unaffected and stay
+  readable.

package/changelogs/CHANGELOGS_0_20_9.md

@@ -0,0 +1,39 @@
+# CDX Manager 0.20.9
+
+## Fixes
+
+- Preserve an existing session when `cdx import --merge` fails. The profile,
+  its record and its state are snapshotted first — symlinks kept as links —
+  and restored on failure; if recovery itself fails, the error names the
+  retained recovery directory instead of leaving the session destroyed.
+  Bundle paths that escape the profile through a link are refused.
+- Stop `cdx cp` from copying the profile's macOS keychain directory. Only the
+  source profile's own keychain entry is transferred, and an overwritten
+  destination entry is restored if the copy fails.
+- Keep Claude authentication working across `cdx ren`. The destination
+  keychain entry is staged before the profile moves, an existing destination
+  entry is refused, and a failed cleanup of the old entry is reported once the
+  renamed session is already usable.
+- Delete a session's Claude keychain credential when the session is removed,
+  so the OAuth token does not outlive the profile and the freed name can be
+  reused by `cdx cp` and `cdx ren`.
+- Refresh Claude quota from the profile-scoped keychain entry before falling
+  back to legacy credential files, so keychain-authenticated sessions no
+  longer read as missing credentials. An unreadable keychain is an explicit
+  error, never a silent "not logged in" — unless a credential file on disk
+  can still answer, in which case `cdx` uses it and says nothing.
+
+- Export keychain-backed Claude authentication. `cdx export --include-auth`
+  carries the profile's keychain entry in the encrypted bundle as its
+  credential file, and `cdx import` restores a usable login, replacing any
+  entry the destination profile already had so the imported credential is the
+  one in effect. A keychain that cannot be read is an explicit error before
+  anything is written, in both text and JSON, so an existing `--force`
+  destination survives it.
+
+## Notes
+
+- A credential restored from a bundle lands in the profile's credential file
+  rather than the keychain; Claude Code moves it back on its next launch.
+- Merge imports temporarily need room for a second copy of the profile being
+  merged into.

package/checksums/release-archives.json

@@ -397,6 +397,28 @@
         "x86_64-pc-windows-msvc": "532fcdabf7ff249eafaea6518668e7a175ae8763de1f23c5abc9bb2c5d4e5eac",
         "x86_64-unknown-linux-musl": "224277ab55219bb5d94386f57fa00bc043537ad97ecf04fd68afd2a7986caa87"
       }
+    },
+    "v0.20.8": {
+      "github_tarball_sha256": "388f32a28e1ae816679947d3422a43d413c665f6b7eb445c9c92e177d7bb2cfa",
+      "github_zip_sha256": "82bfea6857a2e365e4fab7a7996a301a725c4fc98d7d83acfbb676a6aa95ae8e",
+      "tray_assets": {
+        "aarch64-apple-darwin": "38fc94180e73a440cba7dee576271a9189f1050d297456d0d4eebd4314f794b2",
+        "aarch64-unknown-linux-musl": "6713672f6a5effc544d056ae1aacc8929e9c6c63e1f44b7eff50c64fb0395810",
+        "x86_64-apple-darwin": "69611a302855f38fbc79b650004af3aad8f03c7aca65d91d5820bf49fb499edd",
+        "x86_64-pc-windows-msvc": "343245a6ce52275e8e7bd9a380d9e03fd1db3bcf917df3e6cecde2d0be1bfaeb",
+        "x86_64-unknown-linux-musl": "5d6e776b5ce64a062c798c5c00f9e85e003b5b6888cece74173bff1f45247f34"
+      }
+    },
+    "v0.20.9": {
+      "github_tarball_sha256": "1d1989861ba26df76ee3b1d0db98fbc2bbacbeb36277411c45f94ea1fddc0996",
+      "github_zip_sha256": "997e304f71c69bb22c045e29a76313ba2e0fa0227020cd16b2416aee0d64482d",
+      "tray_assets": {
+        "aarch64-apple-darwin": "6e07850c91915d5f2c73d6ae5d44c9ccf9ef149f0a63268a9773f1bf215d4d50",
+        "aarch64-unknown-linux-musl": "d12869b53457de872054ee0edd4822a4bb53325700ee4b58c30a9c777d58a3b9",
+        "x86_64-apple-darwin": "e84c651fa3b20fc99f9d9cd71378a526089292a4122e111bde014159de046b31",
+        "x86_64-pc-windows-msvc": "53e6811d5c0489a6f08ec29d65bdbd5a1375aef64fc30ad72bc7e26d38ffbb6d",
+        "x86_64-unknown-linux-musl": "d35d02bc18ba80413858d8b9943aa24f6424544c4b6e65770f1dce722d346547"
+      }
     }
   }
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "cdx-manager",
-  "version": "0.20.8",
+  "version": "0.20.10",
   "description": "Terminal session manager for Codex and Claude accounts.",
   "license": "MIT",
   "author": "Alexandre Agostini",

package/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "cdx-manager"
-version = "0.20.8"
+version = "0.20.10"
 description = "Terminal session manager for Codex and Claude accounts."
 readme = "README.md"
 requires-python = ">=3.9"

package/src/backup_bundle.py

@@ -17,6 +17,9 @@ _SCRYPT_P = 1
 _PBKDF2_ITERATIONS = 200000
 _AEAD_ALGORITHM = "aes-256-gcm"
 _LEGACY_ALGORITHM = "sha256-xor-hmac"
+_KDF_SCRYPT = "scrypt"
+_KDF_PBKDF2 = "pbkdf2-hmac-sha256"
+_SUPPORTED_KDFS = (_KDF_SCRYPT, _KDF_PBKDF2)
 
 
 def _now_iso():
@@ -47,13 +50,42 @@ def read_bundle_meta(data):
     return wrapper
 
 
-def _derive_keys(passphrase, salt):
-    if not passphrase:
-        raise CdxError("A non-empty passphrase is required for bundles that include auth data.")
-    if isinstance(passphrase, str):
-        passphrase = passphrase.encode("utf-8")
-    if hasattr(hashlib, "scrypt"):
-        key_material = hashlib.scrypt(
+def _available_kdf(kdf):
+    return kdf != _KDF_SCRYPT or hasattr(hashlib, "scrypt")
+
+
+def _default_kdf():
+    """The strongest KDF this runtime can compute. Recorded in the bundle."""
+    return _KDF_SCRYPT if _available_kdf(_KDF_SCRYPT) else _KDF_PBKDF2
+
+
+def _bundle_kdf_candidates(wrapper):
+    """KDFs to try when decoding, in order.
+
+    A recorded KDF is authoritative: the importing runtime's own capabilities
+    must not silently select a different derivation, or a portable bundle stops
+    decoding after a move between machines. Bundles written before the field was
+    honoured record nothing reliable, so those keep the compatibility behaviour
+    of trying every KDF this runtime can compute.
+    """
+    recorded = wrapper.get("kdf")
+    if recorded is None:
+        default = _default_kdf()
+        ordered = [default, *(kdf for kdf in _SUPPORTED_KDFS if kdf != default)]
+        return [kdf for kdf in ordered if _available_kdf(kdf)]
+    if not isinstance(recorded, str) or recorded not in _SUPPORTED_KDFS:
+        raise CdxError("Unsupported bundle key derivation function.")
+    return [recorded]
+
+
+def _derive_key_material(passphrase, salt, kdf):
+    if kdf == _KDF_SCRYPT:
+        if not _available_kdf(_KDF_SCRYPT):
+            raise CdxError(
+                "This bundle records the scrypt key derivation function, which this Python runtime "
+                "does not provide. Decode it with a Python built against OpenSSL scrypt support."
+            )
+        return hashlib.scrypt(
             passphrase,
             salt=salt,
             n=_SCRYPT_N,
@@ -61,19 +93,28 @@ def _derive_keys(passphrase, salt):
             p=_SCRYPT_P,
             dklen=64,
         )
-    else:
-        key_material = hashlib.pbkdf2_hmac(
+    if kdf == _KDF_PBKDF2:
+        return hashlib.pbkdf2_hmac(
             "sha256",
             passphrase,
             salt,
             _PBKDF2_ITERATIONS,
             dklen=64,
         )
+    raise CdxError("Unsupported bundle key derivation function.")
+
+
+def _derive_keys(passphrase, salt, kdf=None):
+    if not passphrase:
+        raise CdxError("A non-empty passphrase is required for bundles that include auth data.")
+    if isinstance(passphrase, str):
+        passphrase = passphrase.encode("utf-8")
+    key_material = _derive_key_material(passphrase, salt, kdf or _default_kdf())
     return key_material[:32], key_material[32:]
 
 
-def _derive_aead_key(passphrase, salt):
-    enc_key, _mac_key = _derive_keys(passphrase, salt)
+def _derive_aead_key(passphrase, salt, kdf=None):
+    enc_key, _mac_key = _derive_keys(passphrase, salt, kdf)
     return enc_key
 
 
@@ -110,11 +151,12 @@ def encode_bundle(payload, include_auth=False, passphrase=None):
     if include_auth:
         salt = os.urandom(_SALT_BYTES)
         nonce = os.urandom(_AEAD_NONCE_BYTES)
-        aesgcm = _load_aesgcm()(_derive_aead_key(passphrase, salt))
+        kdf = _default_kdf()
+        aesgcm = _load_aesgcm()(_derive_aead_key(passphrase, salt, kdf))
         ciphertext = aesgcm.encrypt(nonce, payload_bytes, None)
         wrapper.update({
             "encryption": _AEAD_ALGORITHM,
-            "kdf": "scrypt" if hasattr(hashlib, "scrypt") else "pbkdf2-hmac-sha256",
+            "kdf": kdf,
             "salt": _b64_encode(salt),
             "nonce": _b64_encode(nonce),
             "payload": _b64_encode(ciphertext),
@@ -138,19 +180,33 @@ def decode_bundle(data, passphrase=None):
         nonce = _b64_decode(wrapper.get("nonce", ""))
         ciphertext = _b64_decode(payload_b64)
         algorithm = wrapper.get("encryption") or _LEGACY_ALGORITHM
+        kdf_candidates = _bundle_kdf_candidates(wrapper)
         if algorithm == _AEAD_ALGORITHM:
-            aesgcm = _load_aesgcm()(_derive_aead_key(passphrase, salt))
-            try:
-                payload_bytes = aesgcm.decrypt(nonce, ciphertext, None)
-            except Exception as error:
-                raise CdxError("Invalid bundle passphrase or corrupted bundle.") from error
+            aead = _load_aesgcm()
+            payload_bytes = None
+            failure = None
+            for kdf in kdf_candidates:
+                # Derivation errors are about the bundle, not the passphrase, so
+                # they must escape rather than be retried as a bad secret.
+                cipher = aead(_derive_aead_key(passphrase, salt, kdf))
+                try:
+                    payload_bytes = cipher.decrypt(nonce, ciphertext, None)
+                    break
+                except Exception as error:  # a wrong KDF looks exactly like a wrong passphrase.
+                    failure = error
+            if payload_bytes is None:
+                raise CdxError("Invalid bundle passphrase or corrupted bundle.") from failure
         elif algorithm == _LEGACY_ALGORITHM:
             expected_mac = _b64_decode(wrapper.get("hmac_sha256", ""))
-            enc_key, mac_key = _derive_keys(passphrase, salt)
-            actual_mac = hmac.new(mac_key, nonce + ciphertext, hashlib.sha256).digest()
-            if not hmac.compare_digest(actual_mac, expected_mac):
+            payload_bytes = None
+            for kdf in kdf_candidates:
+                enc_key, mac_key = _derive_keys(passphrase, salt, kdf)
+                actual_mac = hmac.new(mac_key, nonce + ciphertext, hashlib.sha256).digest()
+                if hmac.compare_digest(actual_mac, expected_mac):
+                    payload_bytes = _xor_keystream(ciphertext, enc_key, nonce)
+                    break
+            if payload_bytes is None:
                 raise CdxError("Invalid bundle passphrase or corrupted bundle.")
-            payload_bytes = _xor_keystream(ciphertext, enc_key, nonce)
         else:
             raise CdxError("Unsupported bundle encryption algorithm.")
     else:

package/src/claude_credentials.py

@@ -0,0 +1,148 @@
+"""Profile-scoped macOS credential access, matching Claude Code 2.1.263."""
+
+import hashlib
+import json
+import os
+import re
+import subprocess
+import sys
+import unicodedata
+from contextlib import contextmanager
+
+from .errors import CdxError
+
+KEYCHAIN_TIMEOUT_SECONDS = 5
+
+
+def _keychain_identity(auth_home):
+    if not auth_home or not os.path.isabs(auth_home):
+        raise CdxError("Claude keychain access requires an absolute profile home.")
+    user = os.environ.get("USER")
+    if not user:
+        import pwd
+        user = pwd.getpwuid(os.getuid()).pw_name
+    if not re.fullmatch(r"[a-zA-Z0-9._-]+", user):
+        user = "claude-code-user"
+    config_dir = unicodedata.normalize("NFC", os.path.join(auth_home, ".claude"))
+    suffix = hashlib.sha256(config_dir.encode("utf-8")).hexdigest()[:8]
+    return user, f"Claude Code-credentials-{suffix}"
+
+
+def _reject_custom_oauth():
+    """Only writes are guarded: a custom endpoint stores credentials elsewhere,
+    so reading the standard entry is harmless but changing it is not."""
+    if os.environ.get("USE_LOCAL_OAUTH") or os.environ.get("CLAUDE_CODE_CUSTOM_OAUTH_URL"):
+        raise CdxError("CDX keychain operations do not support custom Claude OAuth endpoints.")
+
+
+def _security(args, *, input_text=None):
+    import pwd
+
+    # HOME may already point at a profile. Always resolve the operator's actual keychain.
+    try:
+        env = {**os.environ, "HOME": pwd.getpwuid(os.getuid()).pw_dir}
+        result = subprocess.run(["/usr/bin/security", *args], input=input_text,
+                                capture_output=True, text=True, timeout=KEYCHAIN_TIMEOUT_SECONDS,
+                                env=env, check=False)
+    except subprocess.TimeoutExpired:
+        raise CdxError("Claude keychain operation timed out; authentication was not verified.") from None
+    except (OSError, KeyError, UnicodeError):
+        raise CdxError("Claude keychain is unavailable; authentication was not verified.") from None
+    return result
+
+
+def read_keychain_credentials(auth_home):
+    if sys.platform != "darwin" or not auth_home:
+        return None
+    user, service = _keychain_identity(auth_home)
+    result = _security(["find-generic-password", "-a", user, "-s", service, "-w"])
+    if result.returncode == 44:  # errSecItemNotFound, not a locked or missing keychain.
+        return None
+    if result.returncode != 0:
+        raise CdxError("Claude keychain access failed; unlock or allow access to the profile credential.")
+    try:
+        data = json.loads(result.stdout)
+    except (ValueError, TypeError):
+        raise CdxError("Claude keychain credential data is malformed.") from None
+    if not isinstance(data, dict):
+        raise CdxError("Claude keychain credential data is malformed.")
+    return data
+
+
+def peek_keychain_credentials(auth_home):
+    """The profile entry, or None when the keychain cannot answer.
+
+    For callers with a file-based fallback. Callers that would otherwise
+    report a locked keychain as a logged-out profile use the strict read.
+    """
+    try:
+        return read_keychain_credentials(auth_home)
+    except CdxError:
+        return None
+
+
+def write_keychain_credentials(auth_home, data):
+    _reject_custom_oauth()
+    user, service = _keychain_identity(auth_home)
+    encoded = json.dumps(data, ensure_ascii=True, separators=(",", ":")).encode("utf-8").hex()
+    command = f'add-generic-password -U -a "{user}" -s "{service}" -X "{encoded}"\n'
+    # ponytail: security -i has a 4096-byte line limit; use native Security APIs if larger entries are needed.
+    if len(command) > 4000:
+        raise CdxError(
+            "Claude profile credential exceeds the safe keychain transfer size; nothing was changed. "
+            "Create the session and log in inside it instead of transferring the credential."
+        )
+    # Credentials travel through stdin, never argv, shell text or error diagnostics.
+    result = _security(["-i"], input_text=command)
+    if result.returncode != 0:
+        raise CdxError("Could not write the destination Claude keychain credential.")
+    # security's interactive driver may exit successfully after a failed command.
+    if read_keychain_credentials(auth_home) != data:
+        raise CdxError("Destination Claude keychain credential verification failed.")
+
+
+def delete_keychain_credentials(auth_home):
+    # Same guard as the read: off macOS there is no keychain to clear, and
+    # `cdx rm`/`cdx import` must not fail on a missing `security` binary.
+    if sys.platform != "darwin" or not auth_home:
+        return
+    _reject_custom_oauth()
+    user, service = _keychain_identity(auth_home)
+    result = _security(["delete-generic-password", "-a", user, "-s", service])
+    if result.returncode not in (0, 44):
+        raise CdxError("Could not remove the profile's Claude keychain credential.")
+
+
+@contextmanager
+def copy_keychain_credentials(source_home, dest_home, *, overwrite=False):
+    """Stage a profile credential and restore the destination if its operation fails."""
+    if sys.platform != "darwin":
+        yield False
+        return
+    if _keychain_identity(source_home) == _keychain_identity(dest_home):
+        raise CdxError("Source and destination Claude keychain identities collide.")
+    source = read_keychain_credentials(source_home)
+    previous = read_keychain_credentials(dest_home)
+    if previous is not None and not overwrite:
+        raise CdxError(
+            "Destination already has a Claude keychain credential; refusing to overwrite it. "
+            f"If no session owns it, clear it with: security delete-generic-password -s '{_keychain_identity(dest_home)[1]}'"
+        )
+    changed = source != previous
+    try:
+        if changed:
+            if source is None:
+                delete_keychain_credentials(dest_home)
+            else:
+                write_keychain_credentials(dest_home, source)
+        yield source is not None
+    except Exception:
+        if changed:
+            try:
+                if previous is None:
+                    delete_keychain_credentials(dest_home)
+                else:
+                    write_keychain_credentials(dest_home, previous)
+            except CdxError:
+                raise CdxError("Profile operation failed; destination keychain recovery is incomplete. Source credentials were retained.") from None
+        raise

package/src/claude_usage.py

@@ -8,6 +8,12 @@ import urllib.error
 import urllib.request
 from datetime import datetime, timezone
 
+try:  # POSIX only; the keychain wiring below is macOS-specific anyway.
+    import pwd
+except ImportError:  # pragma: no cover - Windows
+    pwd = None
+
+from .claude_credentials import read_keychain_credentials
 from .errors import CdxError
 
 MONTH_ABBR = ["Jan", "Feb", "Mar", "Apr", "May", "Jun",
@@ -45,6 +51,20 @@ def _decode_jwt_claims(token):
 
 
 def _read_claude_credentials(auth_home):
+    # An unusable keychain is only an error when no credential file answers
+    # either: a locked keychain must not read as a logged-out profile, and
+    # must not hide a credential that is sitting on disk.
+    keychain_error = None
+    try:
+        keychain = read_keychain_credentials(auth_home)
+    except CdxError as error:
+        keychain, keychain_error = None, error
+    if keychain is not None:
+        creds = keychain.get("claudeAiOauth")
+        token = _clean_oauth_token(creds.get("accessToken")) if isinstance(creds, dict) else None
+        if token:
+            return {**creds, "accessToken": token}
+        keychain_error = CdxError("Claude keychain OAuth credential is malformed.")
     cred_path = os.path.join(auth_home, ".claude", ".credentials.json")
     try:
         with open(cred_path, encoding="utf-8") as f:
@@ -65,9 +85,66 @@ def _read_claude_credentials(auth_home):
             return {"accessToken": token}
     except (FileNotFoundError, json.JSONDecodeError, OSError):
         pass
+
+    if keychain_error is not None:
+        raise keychain_error
     return None
 
 
+def _link_macos_keychain(auth_home):
+    """Make the operator's login keychain reachable from a redirected home.
+
+    macOS resolves the login keychain through `$HOME/Library/Keychains`.
+    Profile isolation redirects HOME (see `_home_env_overrides`), so that path
+    does not exist: every Claude Code launch then raises a "Keychain Not Found"
+    dialog before falling back to a plaintext credentials file. Linking the
+    real keychain directory into the profile home restores the lookup. Failure
+    is non-fatal, and deliberately quiet: the profile simply keeps the
+    file-based credentials it already used.
+    """
+    if sys.platform != "darwin" or pwd is None:
+        return
+    try:
+        real_home = pwd.getpwuid(os.getuid()).pw_dir
+    except (KeyError, OSError):
+        return
+    source = os.path.join(real_home, "Library", "Keychains")
+    if not os.path.isdir(source):
+        return
+    link = os.path.join(auth_home, "Library", "Keychains")
+    if os.path.realpath(link) == os.path.realpath(source):
+        return
+    try:
+        os.makedirs(os.path.dirname(link), exist_ok=True)
+        if os.path.islink(link):
+            os.unlink(link)
+        os.symlink(source, link)
+    except OSError:
+        return
+
+
+def _secure_storage_overrides(auth_home):
+    """Key Claude Code's credential storage to this profile.
+
+    Claude Code names its stored credential from
+    `CLAUDE_SECURESTORAGE_CONFIG_DIR`, falling back to `CLAUDE_CONFIG_DIR`,
+    which cdx clears to keep profile credentials isolated. With neither set,
+    every profile writes the same entry, so any store shared between profiles
+    would have them overwrite each other. Only macOS reads such a store today
+    (the login keychain, reached through `/usr/bin/security`); Windows
+    Credential Manager sits behind an opt-in flag and Linux has no keyring
+    backend, so elsewhere this is inert but keeps profiles isolated should that
+    change.
+
+    The value must be the config dir Claude Code would have resolved on its own
+    -- `<home>/.claude`, since cdx leaves `CLAUDE_CONFIG_DIR` unset -- because
+    the variable overrides that directory as well as naming the entry. Any
+    other value would also move where credentials are read from.
+    """
+    _link_macos_keychain(auth_home)
+    return {"CLAUDE_SECURESTORAGE_CONFIG_DIR": os.path.join(auth_home, ".claude")}
+
+
 def _home_env_overrides(auth_home):
     overrides = {
         "HOME": auth_home,
@@ -78,6 +155,7 @@ def _home_env_overrides(auth_home):
         overrides["USERPROFILE"] = auth_home
         overrides["HOMEDRIVE"] = os.path.splitdrive(auth_home)[0] or "C:"
         overrides["HOMEPATH"] = os.path.splitdrive(auth_home)[1] or auth_home
+    overrides.update(_secure_storage_overrides(auth_home))
     return overrides
 
 

package/src/commands/backup.py

@@ -109,4 +109,9 @@ def handle_import(rest, ctx):
         _write_json(ctx, payload)
         return 0
     ctx["out"](f"{_success(message, ctx['use_color'])}\n")
+    retained = result.get("retained_local_credentials") or []
+    if retained:
+        # Merge keeps local values, so say which sessions kept their own login
+        # rather than leaving the operator to guess which credential is live.
+        ctx["out"](f"Kept the existing local Claude authentication for: {', '.join(retained)}\n")
     return 0