cdx-manager 0.20.9 → 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.9-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.
 

package/VERSION

@@ -1 +1 @@
-0.20.9
+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/checksums/release-archives.json

@@ -408,6 +408,17 @@
         "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.9",
+  "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.9"
+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/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

package/src/commands/runs.py

@@ -3,6 +3,7 @@
 Split out of cli_commands.py. Moved verbatim; re-exported by cli_commands.
 """
 
+import importlib.util
 import os
 import subprocess
 import sys
@@ -147,9 +148,22 @@ def _cdx_self_command():
     script has no reliable executable bit on Windows (`os.access(X_OK)` is true
     for any existing file there) and a shebang script handed to CreateProcess
     does not start at all.
+
+    Named from the top-level package, not this module's own package: `cli` lives
+    beside `commands`, so `{__package__}.cli` resolves to a module that does not
+    exist. The import root is the parent of every package component, which for
+    src/commands/runs.py is the repository root rather than src/.
     """
-    package_root = os.path.dirname(os.path.dirname(os.path.abspath(__file__)))
-    return [sys.executable, "-m", f"{__package__}.cli"], package_root
+    package = (__package__ or "src.commands").split(".")[0]
+    module = f"{package}.cli"
+    package_root = os.path.abspath(__file__)
+    for _ in range((__package__ or "src.commands").count(".") + 2):
+        package_root = os.path.dirname(package_root)
+    if importlib.util.find_spec(module) is None:
+        # A wrong module name reports a launched run that never runs, so fail
+        # here where the caller still gets the error.
+        raise CdxError(f"Cannot launch a detached run: the cdx CLI module {module} was not found.")
+    return [sys.executable, "-m", module], package_root
 
 def _detached_spawn_options():
     """Platform flags that keep the child alive after this process exits.
@@ -751,6 +765,7 @@ def handle_run(rest, ctx):
         return error.exit_code or 1
     except CdxError as error:
         run_info = getattr(error, "run_info", None)
+        cancelled = bool(getattr(error, "cancelled", False))
         final_payload = run_result_payload(
             API_SCHEMA_VERSION,
             False,
@@ -758,14 +773,16 @@ def handle_run(rest, ctx):
             locals().get("session"),
             run_info=run_info,
             error=error,
-            error_source="cdx",
-            error_code=run_cdx_error_code(error),
+            error_source="provider" if cancelled else "cdx",
+            error_code="run_cancelled" if cancelled else run_cdx_error_code(error),
             selection_row=selection_row,
         )
         if registry and run_id:
             registry.finish(
                 run_id,
-                status="failed",
+                # A cancelled run is neither a task failure nor a timeout, and a
+                # caller has to be able to tell the three apart.
+                status="cancelled" if cancelled else "failed",
                 final_payload=final_payload,
                 run_info=run_info,
                 error=final_payload.get("error"),

package/src/context_store.py

@@ -2,6 +2,7 @@ import hashlib
 import os
 import shlex
 import subprocess
+import threading
 from datetime import datetime
 from urllib.parse import quote, unquote
 
@@ -105,13 +106,31 @@ def append_context(base_dir, note, cwd=None):
     return append_context_path(get_context_path(base_dir, cwd), note)
 
 
+# An append is a read-modify-write, and the write is atomic per attempt, so two
+# concurrent appends that both read the pre-existing text produce one file that
+# is missing a note the caller was told had been accepted. Parallel agents append
+# to the same scope by design, so the sequence is serialized here.
+_APPEND_LOCKS = {}
+_APPEND_LOCKS_GUARD = threading.Lock()
+
+
+def _append_lock(path):
+    key = os.path.abspath(path)
+    with _APPEND_LOCKS_GUARD:
+        lock = _APPEND_LOCKS.get(key)
+        if lock is None:
+            lock = _APPEND_LOCKS[key] = threading.Lock()
+        return lock
+
+
 def append_context_path(path, note):
     note = str(note or "").strip()
     if not note:
         raise CdxError("Memory append requires text.")
-    current = read_context_path(path).rstrip()
-    content = f"{current}\n{note}" if current else note
-    return write_context_path(path, content)
+    with _append_lock(path):
+        current = read_context_path(path).rstrip()
+        content = f"{current}\n{note}" if current else note
+        return write_context_path(path, content)
 
 
 def init_context(base_dir, cwd=None):

package/src/provider_runtime.py

@@ -1023,6 +1023,7 @@ def _run_headless_provider_command(session, cwd=None, env_override=None, initial
 
     child = None
     timed_out = False
+    cancelled = False
     with open(paths["stdout_path"], "w", encoding="utf-8", errors="replace") as stdout_file, \
             open(paths["stderr_path"], "w", encoding="utf-8", errors="replace") as stderr_file:
         options = {k: v for k, v in spec.get("options", {}).items() if k not in ("stdio", "stdout", "stderr")}
@@ -1056,6 +1057,25 @@ def _run_headless_provider_command(session, cwd=None, env_override=None, initial
         except subprocess.TimeoutExpired:
             timed_out = True
             _terminate_child_tree(child)
+        except KeyboardInterrupt:
+            # The provider has its own process group, so unwinding only this
+            # supervisor would leave it consuming quota and writing to the
+            # workspace. Terminate and reap it, then report the cancellation so
+            # the run still gets a terminal record.
+            cancelled = True
+            _terminate_child_tree(child)
+
+    if cancelled:
+        _combine_headless_transcript(paths)
+        returncode = getattr(child, "returncode", None)
+        cdx_error = CdxError(f"{spec['label']} run was cancelled.", 130)
+        cdx_error.cancelled = True
+        cdx_error.run_info = {
+            **_headless_run_info(paths, spec, start_time, 130 if returncode in (None, 0) else returncode),
+            "pid": getattr(child, "pid", None),
+            "cancelled": True,
+        }
+        raise cdx_error
 
     _combine_headless_transcript(paths)
     end_time = datetime.now(timezone.utc)

package/src/session_backup.py

@@ -12,7 +12,11 @@ import shutil
 import tempfile
 
 from .backup_bundle import decode_bundle, encode_bundle
-from .claude_credentials import delete_keychain_credentials, read_keychain_credentials
+from .claude_credentials import (
+    delete_keychain_credentials,
+    read_keychain_credentials,
+    write_keychain_credentials,
+)
 from .config import PROVIDER_CLAUDE
 from .errors import CdxError
 from .fs_utils import atomic_write, remove_tree
@@ -160,6 +164,19 @@ def _resolve_session_subset(store, session_names):
         selected.append(session)
     return selected
 
+def _restore_import_credential(auth_home, credential):
+    """Put the destination's own Claude credential back after a failed import.
+
+    The snapshot is held in memory for the length of the import rather than
+    written beside the profile: a rollback only has to survive this process, and
+    a plaintext token in a temporary directory would be a worse trade.
+    """
+    if credential is None:
+        return
+    if read_keychain_credentials(auth_home) == credential:
+        return
+    write_keychain_credentials(auth_home, credential)
+
 def _restore_import_backup(store, name, backup_root, session_root, old_record, old_state):
     if os.path.exists(session_root):
         remove_tree(session_root)
@@ -258,6 +275,7 @@ def import_bundle(base_dir, store, file_path,
         if missing_names:
             raise CdxError(f"Bundle does not contain requested sessions: {', '.join(missing_names)}")
     names = [item["name"] for item in imported_sessions]
+    retained_credential_names = []
 
     existing = {session["name"] for session in list_sessions(store)}
     conflicts = [name for name in names if name in existing]
@@ -313,6 +331,17 @@ def import_bundle(base_dir, store, file_path,
                 remove_tree(recovery_dir, ignore_errors=True)
                 raise
 
+        # A keychain-only profile has no credential file, so the collision with a
+        # bundle credential exists at the credential-backend level and has to be
+        # resolved there. Read it strictly: refusing an unreadable keychain is
+        # better than importing over a credential we could not preserve.
+        bundle_carries_credential = provider == PROVIDER_CLAUDE and any(
+            item["path"] == CLAUDE_CREDENTIALS_BUNDLE_PATH for item in decoded_profiles.get(name, [])
+        )
+        local_credential = None
+        if bundle_carries_credential and old_record is not None:
+            local_credential = read_keychain_credentials(auth_home)
+
         existing_state_before = None
         try:
             _ensure_private_dir(session_root)
@@ -366,6 +395,11 @@ def import_bundle(base_dir, store, file_path,
                 # In merge mode, skip files that already exist locally.
                 if is_existing and merge and os.path.lexists(dest_path):
                     continue
+                if merge and local_credential is not None and item["path"] == CLAUDE_CREDENTIALS_BUNDLE_PATH:
+                    # Merge keeps local values, and the live keychain entry is this
+                    # profile's credential even though no file represents it.
+                    retained_credential_names.append(name)
+                    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)
@@ -374,10 +408,20 @@ def import_bundle(base_dir, store, file_path,
                 delete_keychain_credentials(auth_home)
             _restore_force_import_profile_paths(name, backup_root, session_root, preserved_profile_paths)
         except Exception:
+            incomplete = []
             try:
                 _restore_import_backup(store, name, backup_root, session_root, old_record, old_state)
             except Exception:
-                raise CdxError(f"Import failed and recovery is incomplete for {name}; recovery data retained at {recovery_dir or session_root}.") from None
+                incomplete.append("local files, the session record, and state")
+            try:
+                _restore_import_credential(auth_home, local_credential)
+            except Exception:
+                incomplete.append("Claude keychain authentication")
+            if incomplete:
+                raise CdxError(
+                    f"Import failed and recovery is incomplete for {name}: could not restore "
+                    f"{' and '.join(incomplete)}. Recovery data retained at {recovery_dir or session_root}."
+                ) from None
             if recovery_dir:
                 remove_tree(recovery_dir, ignore_errors=True)
             raise
@@ -389,4 +433,5 @@ def import_bundle(base_dir, store, file_path,
         "path": file_path,
         "session_names": names,
         "include_auth": bool(decoded["meta"].get("include_auth")),
+        "retained_local_credentials": retained_credential_names,
     }

package/src/tray_install.py

@@ -226,7 +226,15 @@ def install(base_dir, version, download=None, ledger_path=CHECKSUM_LEDGER, targe
     # Best-effort, and after the companion is known to be on disk: the shortcut
     # points at it. A failure here does not fail the install — the tray runs
     # either way, only its toasts would go nowhere, and doctor reports that.
-    shortcut = create_shortcut(executable, env=env)
+    #
+    # Only the install that is about to be live writes it. A staged executable
+    # is going to move, and a shortcut recorded against the staged path is a
+    # broken Start Menu entry the moment it does; the promotion writes it
+    # against the final path instead.
+    shortcut = (
+        create_shortcut(executable, env=env) if record
+        else {"created": False, "path": None, "reason": "staged install; the promotion writes the shortcut"}
+    )
 
     state = {
         "version": STATE_VERSION,
@@ -292,9 +300,9 @@ def align_companion(
     try:
         result = update(
             base_dir, version,
-            download=download, ledger_path=ledger_path, target=target, probe=probe,
+            download=download, ledger_path=ledger_path, target=target, probe=probe, env=env,
         )
-    except TrayInstallError as error:
+    except (TrayInstallError, OSError) as error:
         outcome = {
             "aligned": False,
             "reason": str(error),
@@ -407,7 +415,8 @@ def staged_dir(base_dir):
     return os.path.join(state_dir(base_dir), "companion.staged")
 
 
-def update(base_dir, version, download=None, ledger_path=CHECKSUM_LEDGER, target=None, probe=None):
+def update(base_dir, version, download=None, ledger_path=CHECKSUM_LEDGER, target=None, probe=None,
+           env=None):
     """Replace an installed companion without ever being left with none.
 
     The order is the whole point. The replacement is downloaded, verified and
@@ -444,18 +453,43 @@ def update(base_dir, version, download=None, ledger_path=CHECKSUM_LEDGER, target
     live = os.path.join(state_dir(base_dir), "companion")
     retired = previous_dir(base_dir)
     shutil.rmtree(retired, ignore_errors=True)
-    if os.path.isdir(live):
-        os.rename(live, retired)
-    os.rename(staged, live)
+    retired_live = False
+    try:
+        if os.path.isdir(live):
+            os.rename(live, retired)
+            retired_live = True
+        os.rename(staged, live)
+    except OSError as error:
+        # A failure between the two renames used to leave the recorded
+        # executable pointing at nothing: the install claimed a live companion
+        # and the path was empty. Put the proven one back, and report as a
+        # TrayInstallError so the caller's restart path runs.
+        restored = True
+        if retired_live and not os.path.isdir(live):
+            try:
+                os.rename(retired, live)
+            except OSError:
+                restored = False
+        shutil.rmtree(staged, ignore_errors=True)
+        raise TrayInstallError(
+            f"Could not promote the staged tray companion for CDX {version}: {error}. "
+            + ("The installed one was restored." if restored
+               else f"The previous companion is retained at {retired}.")
+        ) from error
     # The retired copy stays. It used to be deleted here, which left nothing to
     # go back to the moment the replacement turned out not to start — and that
     # is precisely when it is needed. The next update clears it, so at most one
     # extra copy is ever on disk.
 
+    live_executable = fresh["executable"].replace(staged, live, 1)
+    # Written now, against the path that will still exist afterwards, and
+    # recorded so uninstall keeps owning it.
+    shortcut = create_shortcut(live_executable, env=env)
     state = {
         **fresh,
-        "executable": fresh["executable"].replace(staged, live, 1),
-        "paths": [live],
+        "executable": live_executable,
+        "paths": [live] + ([shortcut["path"]] if shortcut["created"] else []),
+        "shortcut": shortcut["path"] if shortcut["created"] else None,
     }
     _record_state(base_dir, state)
     return {"state": state, "replaced": previous.get("cdx_version"), "previous_state": previous}
@@ -496,17 +530,55 @@ def restore_previous(base_dir, previous_state):
         return False
 
 
+# `--print` exits non-zero when CDX itself is unavailable, and that is a
+# diagnostic that ran, not a companion that failed to launch. These are the
+# codes that mean the program never got to run: the exec conventions for "found
+# but not executable" and "not found". Death by signal is reported as a
+# negative returncode and counts the same way.
+_PROBE_LAUNCH_FAILURE_CODES = (126, 127)
+
+
+def probe_command(executable):
+    """How to ask the companion itself for its diagnostic output.
+
+    Not `launch_command`: on macOS that hands the bundle to `open`, which takes
+    `--print` for itself and reports nothing whatsoever about the companion. The
+    binary inside the bundle is what has to run, and an app bundle with no
+    runnable binary in it is exactly the case this gate exists to refuse.
+    """
+    if platform.system() == "Darwin" and executable.endswith(".app"):
+        macos_dir = os.path.join(executable, "Contents", "MacOS")
+        try:
+            entries = sorted(os.listdir(macos_dir))
+        except OSError:
+            return None
+        for entry in entries:
+            candidate = os.path.join(macos_dir, entry)
+            if os.path.isfile(candidate) and os.access(candidate, os.X_OK):
+                return [candidate]
+        return None
+    return [executable]
+
+
 def _probe(executable):
-    """Does this companion start at all? `--print` exits non-zero when CDX is
-    unavailable, which is not the question here, so any completed run counts."""
+    """Does this companion actually run?
+
+    `--print` makes it emit its snapshot and exit, so a bundle that cannot
+    launch — wrong architecture, missing library, no binary inside it — is
+    refused here rather than after the working companion is gone.
+    """
+    command = probe_command(executable)
+    if not command:
+        return False
     try:
-        subprocess.run(  # noqa: S603  (path comes from our own install state)
-            launch_command(executable) + ["--print"],
+        completed = subprocess.run(  # noqa: S603  (path comes from our own install state)
+            command + ["--print"],
             capture_output=True, timeout=20, check=False,
         )
     except (OSError, subprocess.SubprocessError):
         return False
-    return True
+    returncode = completed.returncode
+    return not (returncode < 0 or returncode in _PROBE_LAUNCH_FAILURE_CODES)
 
 
 def interrupted_update(base_dir):