cdx-manager 0.20.9 → 0.20.11

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.11-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.
 
@@ -106,9 +106,56 @@ The reason `cdx` exists: knowing, across every account you own, which one you ca
 
 ### Context handoff
 
-- **Shared handoff context.** Keep a per-workspace Markdown context, or build one from a source session transcript, and install it into another assistant session before switching providers or accounts. Source transcript selection prefers the current workspace when the provider transcript records one, then falls back to the newest source-session transcript.
+- **Transcript-first handoff.** Switch accounts or providers using the source conversation's recorded native identity and verified workspace. CDX never chooses a conversation by file modification time. Missing, stale or mismatched identity requires an explicit choice; JSON/non-interactive callers receive candidate diagnostics instead of a launch.
+- **Instructions before action.** The receiving agent is told to read applicable `AGENTS.md`/`CLAUDE.md` and their required references (including Logics instructions), recover the task from bounded portions of the complete transcript, verify current state, then show a concise objective/state/next-action checkpoint before modifying anything. Existing clear authorization still permits continuation. CDX supplies this prompt; it cannot certify that an agent has understood or obeyed it.
+- **Shared notes remain yours.** `cdx context` and `cdx memory` remain explicit notes. Automatic handoff does not overwrite them or copy authentication. A dated reference to workspace notes is supplementary, never a substitute for the native conversation.
 - **Session transcript capture.** Every launch is recorded to a local log file via `script`, giving you a full terminal transcript for each session.
 
+Run handoff from the intended project directory:
+
+```sh
+cd /path/to/project
+cdx handoff source target --json                 # prepare only, no provider launch
+cdx handoff target                               # use that prepared entry and launch
+cdx handoff source target --source-conversation CONVERSATION_ID
+# Explicit fallback when only a terminal capture is available:
+cdx handoff source target --source-transcript /path/to/source/log/cdx-session.log
+```
+
+The last two source-selection options are mutually exclusive and apply only to
+`SOURCE TARGET`. Without a usable recorded identity, an interactive terminal offers
+up to 20 valid conversations from the current workspace, ordered by actual event
+time for inspection, with no default choice. Blank input or Ctrl-C cancels. A stale
+recorded identity never silently falls back, even if there is only one candidate.
+Run from the conversation's original workspace if its metadata names another directory.
+
+Each preparation writes a private, unique `<target-auth-home>/handoffs/<uuid>.json`
+entry. `context.target_path` in JSON output names that entry; `handoff` contains its
+metadata, including recovery mode, source conversation ID, transcript path, workspace,
+preparation time, readable byte extent and SHA-256. `source_session`/`target_session`
+contain names/providers only. Transcript bodies and credentials are not emitted.
+Unresolved JSON source selection returns `ok: false`, error code
+`handoff_source_unresolved`, a bounded `candidates` array and a nonzero exit status.
+
+The original JSONL remains in place, including early decisions, tool calls/results
+and compaction records. Read it in bounded portions up to `extent_bytes`; there is
+no 120000-character tail replacement. An unfinished final JSONL record is excluded
+from that preparation. Later appends do not change its boundary. Reusing an entry
+checks the original bytes: deletion, truncation or rewriting requires a new handoff,
+not a silent downgrade to notes. Keep the original source profile/transcript available
+until recovery completes. No transcript copy or automatic artifact cleanup is performed;
+entries can be removed after use. A small per-workspace/target pointer chooses the most
+recent preparation for the one-name command; concurrent launches retain their own entry
+path and cannot overwrite each other's entry.
+
+Legacy one-name handoff without a prepared entry reads workspace notes in `notes-only`
+mode and explicitly reports that native history was not recovered. Terminal fallback
+requires a named file from that source session's launch logs and is labelled `degraded`:
+it cannot prove complete history or tools, and its workspace is operator-selected rather
+than verified from native metadata. Native resolution currently supports Codex and Claude.
+All modes ask the recipient to report material gaps, and none bypass provider access rules
+or turn historical tool output into new authorization.
+
 ### Maintenance
 
 - **Launch history.** Inspect recent launches with provider, result, duration, working directory, launch settings, and transcript path.
@@ -515,8 +562,8 @@ cdx history --summary --from 2026-05-01 --to 2026-05-28
 | `cdx can-resume <name> [--json]` | Check whether a session supports native resume without launching the provider |
 | `cdx context show\|path\|init\|edit\|clear\|set\|append [text...] [--json]` | Manage the shared Markdown context for the current workspace |
 | `cdx memory [--global\|--project NAME_OR_PATH] [show\|view\|path\|init\|edit\|clear\|set\|append\|list] [text...] [--json]` | Manage explicit user-controlled memory for the current workspace, global scope, or a named/path project |
-| `cdx handoff <name> [--json]` | Install the current workspace context into a target session and launch it unless `--json` is used |
-| `cdx handoff <source> <target> [--json]` | Build shared context from the source session's latest launch transcript, install it into the target session, and launch the target unless `--json` is used; supports cross-provider handoff |
+| `cdx handoff <name> [--json]` | Reuse the prepared entry for this target/workspace, or use explicitly labelled notes-only recovery if none exists; launch unless `--json` |
+| `cdx handoff <source> <target> [--source-conversation ID\|--source-transcript PATH] [--json]` | Prepare an identity-checked transcript entry and launch the target in the verified workspace unless `--json`; explicit terminal selection is degraded recovery |
 | `cdx rmv <name> [--force] [--json]` | Remove a session and its auth data (prompts for confirmation unless `--force`) |
 | `cdx clean [name] [--yes] [--json]` | Clear launch transcript logs for one session or all sessions after confirmation |
 | `cdx clean profiles (--tmp\|--old-logs DAYS) [--yes] [--json]` | Remove explicit profile cleanup candidates after confirmation: temporary marketplace/plugin staging caches or old `.log` files |

package/VERSION

@@ -1 +1 @@
-0.20.9
+0.20.11

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_11.md

@@ -0,0 +1,37 @@
+# CDX Manager 0.20.11
+
+## Reliable handoff recovery
+
+- Resolve Codex and Claude handoffs using the recorded native conversation ID and
+  verify the workspace. An old transcript touched recently can no longer silently
+  replace the intended conversation. Missing or stale identities return candidates;
+  use `--source-conversation ID` to choose explicitly.
+- Give the receiving agent access to the complete native transcript, including
+  earlier decisions and tool evidence, instead of a flattened 120000-character tail.
+  Each handoff has its own private entry with provenance, a preparation boundary and
+  a checksum. Reusing an entry detects a deleted or rewritten source.
+- Require the receiving agent to read repository instructions and their references,
+  recover user decisions and authorization limits, verify current state, and show a
+  concise recovery checkpoint before making changes. This is a prompt contract, not
+  a guarantee of agent comprehension.
+- Preserve workspace notes as supplementary context rather than overwriting them
+  during handoff. Concurrent preparations retain separate entries; the target starts
+  in the verified workspace.
+
+## Compatibility notes
+
+- `cdx handoff SOURCE TARGET --json` prepares without launching. JSON includes the
+  entry path and source metadata, not transcript bodies or authentication data.
+- `cdx handoff TARGET` reuses the prepared entry for that target and workspace. With
+  no prepared entry, existing workspace notes remain available as explicitly labelled
+  notes-only recovery.
+- Automatic newest-log fallback is removed. For an intentional terminal-only
+  fallback, pass `--source-transcript PATH` naming a source session launch log. This
+  degraded mode cannot verify complete native history or the original workspace.
+- Keep the original transcript available until recovery completes. The entry refers
+  to it in place; it is not a transcript backup.
+
+## Validation
+
+- 1048 Python tests pass, including synthetic handoff regressions and mocked launches.
+- Project lint and Logics corpus validation pass.

package/checksums/release-archives.json

@@ -408,6 +408,28 @@
         "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"
+      }
+    },
+    "v0.20.10": {
+      "github_tarball_sha256": "2b97c8dedc4740d89b8dab5b4ea54c986d211efdf2f9d6c8cbcf014a42bc7eb2",
+      "github_zip_sha256": "144cb5987498a96d78299c1589735b5aef5dd31cd3abfe638c541e83464055b5",
+      "tray_assets": {
+        "aarch64-apple-darwin": "7f89f616c707bfef9f2a0fdccae6e37c22d3b2fb51f6ea2cb5cd5dc8f86446fe",
+        "aarch64-unknown-linux-musl": "4295fb3fd27abacae614360783b704e87d8390023843a32e1626ce986004078f",
+        "x86_64-apple-darwin": "f68422c8da7316ba575579cf689056b58c23213717203a8ea6c48e26337ae2e7",
+        "x86_64-pc-windows-msvc": "ae8eba39b1d9d7e9b97c3b3026561360a6ec00ca154b5d4d215a283fc5566050",
+        "x86_64-unknown-linux-musl": "cfa4245e7704a4c85e4f680275db500c600e46a44aac19d1ec5675deb2be0c58"
+      }
     }
   }
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "cdx-manager",
-  "version": "0.20.9",
+  "version": "0.20.11",
   "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.11"
 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_usage.py

@@ -91,6 +91,32 @@ def _read_claude_credentials(auth_home):
     return None
 
 
+def claude_profile_store_dir(auth_home):
+    """Where `ANTHROPIC_CONFIG_DIR` points: the credential directory, not the home.
+
+    Claude Code treats `ANTHROPIC_CONFIG_DIR` as the root of its profile store
+    and refuses every write beneath it, so whatever this returns is denied to
+    the agent's own file-writing tools. Pointing it at `auth_home` denied the
+    entire profile home -- `.claude/projects/*/memory`, `.claude/settings.json`,
+    `.npm`, `.cargo` -- which is far more than a sign-in store and cost agents
+    their memory and settings with no gain.
+
+    No gain, because the variable does not locate credentials: measured on
+    Claude Code 2.1.268, `HOME` alone authenticates and this variable alone does
+    not. It only draws the deny boundary, so it belongs on the directory that
+    actually holds a credential -- `_write_claude_oauth_token` puts the
+    setup-token fallback in `auth_home/credentials/default.json`.
+
+    Not covered, and deliberately: `auth_home/.claude/.credentials.json`, which
+    Claude Code writes where no OS keyring answers. It cannot be: it sits under
+    `.claude` beside the memory and settings this narrowing exists to free, and
+    `_secure_storage_overrides` explains why that directory cannot move. It
+    keeps its 0600 mode; on macOS it does not exist at all, the login keychain
+    holding the credential instead.
+    """
+    return os.path.join(auth_home, "credentials")
+
+
 def _link_macos_keychain(auth_home):
     """Make the operator's login keychain reachable from a redirected home.
 
@@ -148,7 +174,7 @@ def _secure_storage_overrides(auth_home):
 def _home_env_overrides(auth_home):
     overrides = {
         "HOME": auth_home,
-        "ANTHROPIC_CONFIG_DIR": auth_home,
+        "ANTHROPIC_CONFIG_DIR": claude_profile_store_dir(auth_home),
         "CLAUDE_CODE_DISABLE_GIT_INSTRUCTIONS": "1",
     }
     if sys.platform == "win32":

package/src/cli.py

@@ -260,7 +260,7 @@ def _print_help(use_color=False):
         f"  {_style('cdx resume <name> [--json]', '36', use_color)}",
         f"  {_style('cdx can-resume <name> [--json]', '36', use_color)}",
         f"  {_style('cdx handoff <name> [--json]', '36', use_color)}",
-        f"  {_style('cdx handoff <source> <target> [--json]', '36', use_color)}",
+        f"  {_style('cdx handoff <source> <target> [--source-conversation ID | --source-transcript PATH] [--json]', '36', use_color)}",
         f"  {_style('cdx add [provider] <name> [--model MODEL] [--json]', '36', use_color)}",
         f"  {_style('cdx cp <source> <dest> [--json]', '36', use_color)}",
         f"  {_style('cdx ren <source> <dest> [--json]', '36', use_color)}",

package/src/cli_args.py

@@ -30,7 +30,7 @@ EXPORT_USAGE = "Usage: cdx export <file> [--include-auth] [--force] [--json] [--
 IMPORT_USAGE = "Usage: cdx import <file> [--force|--merge] [--allow-authless-force] [--json] [--sessions name1,name2] [--passphrase-env VAR|--passphrase-stdin]"
 CONTEXT_USAGE = "Usage: cdx context show|path|init|edit|clear|set|append [text...] [--json]"
 MEMORY_USAGE = "Usage: cdx memory [--global|--project NAME_OR_PATH] [show|view|path|init|edit|clear|set|append|list] [text...] [--json]"
-HANDOFF_USAGE = "Usage: cdx handoff <name> [--json] | cdx handoff <source> <target> [--json]"
+HANDOFF_USAGE = "Usage: cdx handoff <name> [--json] | cdx handoff <source> <target> [--source-conversation ID | --source-transcript PATH] [--json]"
 LABEL_USAGE = "Usage: cdx label <name> <label> [--json] | cdx label <name> --clear [--json]"
 SET_USAGE = "Usage: cdx set <name>|--sessions all|a,b|--provider PROVIDER [--power minimal|low|medium|high|xhigh] [--permission review|default|auto|full] [--fast on|off] [--rtk on|off] [--logics on|off] [--model MODEL] [--fallback-model MODEL[,MODEL...]] [--budget USD] [--extra-args 'ARGS'] [--priority 0..100] [--json]"
 UNSET_USAGE = "Usage: cdx unset <name>|--sessions all|a,b|--provider PROVIDER (--power|--reasoning-effort|--permission|--fast|--rtk|--logics|--model|--fallback-model|--budget|--extra-args|--priority|--all) [--json]"

package/src/cli_commands.py

@@ -15,20 +15,16 @@ from .cli_args import STATUS_USAGE  # noqa: F401  (re-exported for cli.py)
 from .cli_helpers import (  # noqa: F401  (several names are re-exported for cli.py / tests)
     API_SCHEMA_VERSION,
     _bootstrap_claude_setup_token,
-    _build_handoff_context,
     _extract_claude_oauth_token,
     _format_bytes,
     _format_launch_config,
     _format_launch_setting_value,
     _format_launch_settings_hint,
-    _handoff_launch_prompt,
     _json_failure,
     _json_success,
-    _latest_handoff_transcript_path,
     _local_now_iso,
     _make_notify_progress,
     _make_status_progress,
-    _read_handoff_transcript,
     _resolve_confirmation,
     _resume_capability_for_session,
     _update_notice_warnings,