cdx-manager 0.5.2 → 0.5.4

package/README.md

@@ -1,6 +1,6 @@
 # CDX Manager
 
-[![License](https://img.shields.io/badge/license-MIT-4C8BF5)](LICENSE) ![Version](https://img.shields.io/badge/version-v0.5.2-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.5.4-4C8BF5) ![Python](https://img.shields.io/badge/python-3.9%2B-3776AB?logo=python&logoColor=white)
 
 **Run multiple Codex and Claude sessions from one terminal. Switch between accounts instantly.**
 
@@ -126,7 +126,7 @@ For a specific version:
 
 ```bash
 curl -fsSL https://raw.githubusercontent.com/AlexAgo83/cdx-manager/main/install.sh -o install.sh
-CDX_VERSION=v0.5.2 sh install.sh
+CDX_VERSION=v0.5.4 sh install.sh
 ```
 
 From source:
@@ -250,7 +250,7 @@ cdx status
 | `cdx enable <name> [--json]` | Re-enable a disabled session |
 | `cdx context show\|path\|init\|edit\|clear\|set [text...] [--json]` | Manage the shared Markdown context for the current workspace |
 | `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 |
+| `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 Codex and Claude targets, including cross-provider handoff |
 | `cdx rmv <name> [--force] [--json]` | Remove a session and its auth data (prompts for confirmation unless `--force`) |
 | `cdx clean [name] [--json]` | Clear launch transcript logs for one session or all sessions |
 | `cdx export <file> [--include-auth] [--sessions a,b] [--passphrase-env VAR] [--force] [--json]` | Export sessions to a portable bundle; `--include-auth` encrypts auth data with a passphrase |

package/changelogs/CHANGELOGS_0_5_3.md

@@ -0,0 +1,42 @@
+# Changelog (`0.5.2 -> 0.5.3`)
+
+Release date: 2026-05-23
+
+## Major Highlights
+
+- Added Claude-compatible handoff launch prompting so Claude targets are told exactly which `shared-context.md` file to read.
+- Added Claude launch transcript capture, enabling transcript-based handoff from Claude source sessions.
+- Enabled cross-provider transcript handoff between Codex and Claude sessions.
+- Prepared the package metadata for the 0.5.3 release across npm, PyPI, CLI version output, and README install examples.
+
+## Claude Handoff
+
+- Passes the handoff prompt to Claude as the initial prompt argument during launch.
+- Installs shared context into the target Claude session profile and references the concrete `shared-context.md` path in the prompt.
+- Captures Claude launch transcripts under the session's `claude-home/log/` directory using the same transcript wrapper path as Codex.
+- Preserves Claude `HOME` isolation while running through the transcript wrapper.
+
+## Cross-Provider Handoff
+
+- Allows `cdx handoff <source> <target>` when the source and target providers differ.
+- Keeps generated handoff context provider-neutral while still recording source and target provider metadata.
+- Preserves target account authentication and does not copy source credentials.
+
+## Documentation
+
+- Updated the command table to document Codex and Claude handoff targets, including cross-provider handoff.
+- Updated the README badge and pinned installer example to `v0.5.3`.
+
+## Validation and Regression Coverage
+
+- Added CLI coverage for Claude-to-Claude transcript handoff.
+- Added CLI coverage for Codex-to-Claude handoff.
+- Added CLI coverage proving non-JSON Claude handoff launches Claude with the resume prompt.
+- Updated existing Claude launch coverage to verify transcript-wrapped launches.
+
+## Validation and Regression Evidence
+
+- `python3 -m pytest test/test_cli_py.py test/test_runtime_py.py`
+- `python3 -m pytest`
+- `npm run lint`
+- `npm test`

package/changelogs/CHANGELOGS_0_5_4.md

@@ -0,0 +1,49 @@
+# Changelog (`0.5.3 -> 0.5.4`)
+
+Release date: 2026-05-23
+
+## Major Highlights
+
+- Added a Logics ADR for the code quality, security, performance, and test coverage improvements completed after `0.5.3`.
+- Hardened bundle import path handling and launch prompt validation without changing CLI contracts or on-disk formats.
+- Improved status parsing and provider handling internals for safer future maintenance.
+- Added structured Codex app-server probe diagnostics while keeping the existing status API behavior compatible.
+
+## Security and Runtime Hardening
+
+- Hardened bundle relative path validation against traversal, absolute paths, and Windows drive paths.
+- Validated provider launch `initial_prompt` type and length before it is passed into subprocess arguments.
+- Replaced mutable signal-capture state with explicit `nonlocal` signal forwarding.
+- Added Linux `notify-send` support with backend timeout handling and shell-free notification arguments.
+
+## Status and Provider Internals
+
+- Moved status extraction regex compilation to module-level constants.
+- Added shared provider constants for Codex and Claude identity checks.
+- Improved Claude status refresh handling for sync and async refresh functions without per-thread event loops.
+- Added `fetch_codex_rate_limit_diagnostic()` to expose structured failure reasons such as missing auth home, initialize failure, app-server read failure, missing rate limits, and missing Codex CLI.
+
+## CLI Parser Maintenance
+
+- Factorized more CLI flag parsing through a shared flat-flag parser.
+- Added `--flag=value` support where appropriate, including `cdx notify --poll=<seconds>`.
+- Preserved existing usage errors and JSON/non-JSON output contracts.
+
+## Documentation
+
+- Added `logics/architecture/adr_001_code_quality_and_security_improvements.md` documenting the security, test, quality, and performance decisions.
+- Updated package metadata, CLI version output, README badge, and pinned installer example to `v0.5.4`.
+
+## Validation and Regression Coverage
+
+- Added direct session-store rollback tests for add, remove, rename, and replace failure paths.
+- Added status-source tests for key-value, Codex block, Claude block, artifact selection, reset timestamp parsing, and safe relative paths.
+- Added notification tests for macOS, Linux, backend fallback, timeout, and argument handling.
+- Added CLI parser tests for update, status, repair, export/import subsets, corrupt bundles, and clean behavior with and without logs.
+- Added Codex app-server diagnostic tests for success and failure cases.
+
+## Validation and Regression Evidence
+
+- `npm test`
+- `npm run lint`
+- `python logics/skills/logics.py lint --require-status`

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "cdx-manager",
-  "version": "0.5.2",
+  "version": "0.5.4",
   "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.5.2"
+version = "0.5.4"
 description = "Terminal session manager for Codex and Claude accounts."
 readme = "README.md"
 requires-python = ">=3.9"

package/src/claude_refresh.py

@@ -3,6 +3,7 @@ import threading
 from datetime import datetime, timezone
 
 from .claude_usage import refresh_claude_session_status
+from .config import PROVIDER_CLAUDE
 from .errors import CdxError
 
 CLAUDE_REFRESH_TTL_SECONDS = 10 * 60
@@ -35,7 +36,7 @@ def _refresh_claude_sessions(service, refresh_fn=None, target_names=None, force=
     sessions = service["list_sessions"]()
     claude_sessions = [
         s for s in sessions
-        if s["provider"] == "claude"
+        if s["provider"] == PROVIDER_CLAUDE
         and s.get("enabled", True) is not False
         and (not target_names or s["name"] in target_names)
         and (force or _is_stale(s, ttl_seconds=ttl_seconds))
@@ -45,25 +46,41 @@ def _refresh_claude_sessions(service, refresh_fn=None, target_names=None, force=
 
     errors = []
     results = {}
-    threads = []
 
-    def fetch(s):
-        try:
-            usage = refresh_fn(s)
-            if inspect.isawaitable(usage):
-                import asyncio
-                usage = asyncio.run(usage)
-            if usage:
-                results[s["name"]] = usage
-        except Exception as e:
-            errors.append({"session": s["name"], "error": e})
-
-    for s in claude_sessions:
-        t = threading.Thread(target=fetch, args=(s,))
-        threads.append(t)
-        t.start()
-    for t in threads:
-        t.join()
+    if inspect.iscoroutinefunction(refresh_fn):
+        import asyncio
+
+        async def fetch_all():
+            async def fetch_async(s):
+                try:
+                    usage = await refresh_fn(s)
+                    if usage:
+                        results[s["name"]] = usage
+                except Exception as e:
+                    errors.append({"session": s["name"], "error": e})
+
+            await asyncio.gather(*(fetch_async(s) for s in claude_sessions))
+
+        asyncio.run(fetch_all())
+    else:
+        threads = []
+
+        def fetch(s):
+            try:
+                usage = refresh_fn(s)
+                if inspect.isawaitable(usage):
+                    raise CdxError("Claude refresh function returned an awaitable from a sync callable.")
+                if usage:
+                    results[s["name"]] = usage
+            except Exception as e:
+                errors.append({"session": s["name"], "error": e})
+
+        for s in claude_sessions:
+            t = threading.Thread(target=fetch, args=(s,), daemon=True)
+            threads.append(t)
+            t.start()
+        for t in threads:
+            t.join(timeout=10)
 
     for name, usage in results.items():
         try:

package/src/cli.py

@@ -49,7 +49,7 @@ from .status_view import (
 )
 from .update_check import check_for_update
 
-VERSION = "0.5.2"
+VERSION = "0.5.4"
 
 
 # ---------------------------------------------------------------------------

package/src/cli_commands.py

@@ -7,6 +7,7 @@ from datetime import datetime
 
 from .claude_refresh import _refresh_claude_sessions
 from .cli_render import _dim, _info, _success, _warn
+from .config import PROVIDER_CODEX
 from .context_store import (
     clear_context,
     edit_context,
@@ -111,9 +112,16 @@ def _build_handoff_context(source, target, transcript_path, transcript, truncate
     ])
 
 
-def _handoff_launch_prompt():
+def _handoff_launch_prompt(session, install=None):
+    if session.get("provider") == PROVIDER_CODEX:
+        context_ref = "$CODEX_HOME/shared-context.md"
+    else:
+        context_ref = (install or {}).get("target_path") or os.path.join(
+            session.get("authHome") or session.get("sessionRoot") or "~",
+            "shared-context.md",
+        )
     return (
-        "Read $CODEX_HOME/shared-context.md first, then resume the previous session "
+        f"Read {context_ref} first, then resume the previous session "
         "from the latest actionable state. Do not ask me to paste the context again."
     )
 
@@ -124,11 +132,54 @@ def _parse_json_flag(args):
     return json_flag, cleaned
 
 
+def _parse_flag_args(args, schema, usage, positionals_key=None, max_positionals=0):
+    parsed = {spec["key"]: spec.get("default") for spec in schema.values()}
+    positionals = []
+    index = 0
+    while index < len(args):
+        arg = args[index]
+        if arg in schema:
+            spec = schema[arg]
+            if spec["type"] == "bool":
+                parsed[spec["key"]] = True
+                index += 1
+                continue
+            value, index = _read_option_value(args, index, usage)
+            parsed[spec["key"]] = spec.get("transform", lambda item: item)(value)
+            continue
+        if arg.startswith("--") and "=" in arg:
+            flag, value = arg.split("=", 1)
+            spec = schema.get(flag)
+            if not spec or spec["type"] == "bool":
+                raise CdxError(usage)
+            parsed[spec["key"]] = spec.get("transform", lambda item: item)(value)
+            index += 1
+            continue
+        if arg.startswith("-"):
+            raise CdxError(usage)
+        positionals.append(arg)
+        if len(positionals) > max_positionals:
+            raise CdxError(usage)
+        index += 1
+
+    if positionals_key is not None:
+        parsed[positionals_key] = positionals
+    return parsed
+
+
 def _parse_add_args(args):
-    if len(args) == 1:
-        return {"provider": "codex", "name": args[0]}
-    if len(args) == 2:
-        return {"provider": args[0], "name": args[1]}
+    parsed = _parse_flag_args(
+        args,
+        {},
+        "Usage: cdx add [provider] <name> [--json]",
+        positionals_key="values",
+        max_positionals=2,
+    )
+    values = parsed["values"]
+    if len(values) == 1:
+        return {"provider": PROVIDER_CODEX, "name": values[0]}
+    if len(values) == 2:
+        return {"provider": values[0], "name": values[1]}
     raise CdxError("Usage: cdx add [provider] <name> [--json]")
 
 
@@ -145,19 +196,21 @@ def _parse_rename_args(args):
 
 
 def _parse_remove_args(args):
-    force = "--force" in args
-    names = [a for a in args if a != "--force"]
-    unknown = [a for a in args if a.startswith("-") and a != "--force"]
-    if unknown or len(names) != 1 or len(args) > 2:
+    parsed = _parse_flag_args(args, {
+        "--force": {"key": "force", "type": "bool", "default": False},
+    }, "Usage: cdx rmv <name> [--force] [--json]", positionals_key="names", max_positionals=1)
+    if len(parsed["names"]) != 1:
         raise CdxError("Usage: cdx rmv <name> [--force] [--json]")
-    return {"name": names[0], "force": force}
+    return {"name": parsed["names"][0], "force": parsed["force"]}
 
 
 def _parse_toggle_args(args, usage):
-    json_flag, cleaned = _parse_json_flag(args)
-    if len(cleaned) != 1:
+    parsed = _parse_flag_args(args, {
+        "--json": {"key": "json", "type": "bool", "default": False},
+    }, usage, positionals_key="names", max_positionals=1)
+    if len(parsed["names"]) != 1:
         raise CdxError(usage)
-    return {"name": cleaned[0], "json": json_flag}
+    return {"name": parsed["names"][0], "json": parsed["json"]}
 
 
 def _read_option_value(args, index, usage):
@@ -176,37 +229,12 @@ def _parse_session_names(value):
 
 
 def _parse_update_args(args):
-    parsed = {
-        "check": False,
-        "json": False,
-        "yes": False,
-        "version": None,
-    }
-    index = 0
-    while index < len(args):
-        arg = args[index]
-        if arg == "--check":
-            parsed["check"] = True
-            index += 1
-            continue
-        if arg == "--json":
-            parsed["json"] = True
-            index += 1
-            continue
-        if arg == "--yes":
-            parsed["yes"] = True
-            index += 1
-            continue
-        if arg == "--version":
-            value, index = _read_option_value(args, index, UPDATE_USAGE)
-            parsed["version"] = value
-            continue
-        if arg.startswith("--version="):
-            parsed["version"] = arg.split("=", 1)[1]
-            index += 1
-            continue
-        raise CdxError(UPDATE_USAGE)
-
+    parsed = _parse_flag_args(args, {
+        "--check": {"key": "check", "type": "bool", "default": False},
+        "--json": {"key": "json", "type": "bool", "default": False},
+        "--yes": {"key": "yes", "type": "bool", "default": False},
+        "--version": {"key": "version", "type": "str", "default": None},
+    }, UPDATE_USAGE)
     if parsed["check"] and parsed["version"]:
         raise CdxError("Usage: cdx update --check cannot be combined with --version.")
     if parsed["version"] is not None and not parsed["version"].strip():
@@ -215,52 +243,19 @@ def _parse_update_args(args):
 
 
 def _parse_export_args(args):
-    parsed = {
-        "file_path": None,
-        "include_auth": False,
-        "force": False,
-        "json": False,
-        "session_names": None,
-        "passphrase_env": None,
-    }
-    index = 0
-    while index < len(args):
-        arg = args[index]
-        if arg == "--include-auth":
-            parsed["include_auth"] = True
-            index += 1
-            continue
-        if arg == "--force":
-            parsed["force"] = True
-            index += 1
-            continue
-        if arg == "--json":
-            parsed["json"] = True
-            index += 1
-            continue
-        if arg == "--sessions":
-            value, index = _read_option_value(args, index, EXPORT_USAGE)
-            parsed["session_names"] = _parse_session_names(value)
-            continue
-        if arg.startswith("--sessions="):
-            parsed["session_names"] = _parse_session_names(arg.split("=", 1)[1])
-            index += 1
-            continue
-        if arg == "--passphrase-env":
-            value, index = _read_option_value(args, index, EXPORT_USAGE)
-            parsed["passphrase_env"] = value
-            continue
-        if arg.startswith("--passphrase-env="):
-            parsed["passphrase_env"] = arg.split("=", 1)[1]
-            index += 1
-            continue
-        if arg.startswith("-"):
-            raise CdxError(EXPORT_USAGE)
-        if parsed["file_path"] is not None:
-            raise CdxError(EXPORT_USAGE)
-        parsed["file_path"] = arg
-        index += 1
-
+    parsed = _parse_flag_args(args, {
+        "--include-auth": {"key": "include_auth", "type": "bool", "default": False},
+        "--force": {"key": "force", "type": "bool", "default": False},
+        "--json": {"key": "json", "type": "bool", "default": False},
+        "--sessions": {
+            "key": "session_names",
+            "type": "str",
+            "default": None,
+            "transform": _parse_session_names,
+        },
+        "--passphrase-env": {"key": "passphrase_env", "type": "str", "default": None},
+    }, EXPORT_USAGE, positionals_key="positionals", max_positionals=1)
+    parsed["file_path"] = parsed.pop("positionals")[0] if parsed["positionals"] else None
     if not parsed["file_path"]:
         raise CdxError(EXPORT_USAGE)
     if parsed["passphrase_env"] and not parsed["include_auth"]:
@@ -269,47 +264,18 @@ def _parse_export_args(args):
 
 
 def _parse_import_args(args):
-    parsed = {
-        "file_path": None,
-        "force": False,
-        "json": False,
-        "session_names": None,
-        "passphrase_env": None,
-    }
-    index = 0
-    while index < len(args):
-        arg = args[index]
-        if arg == "--force":
-            parsed["force"] = True
-            index += 1
-            continue
-        if arg == "--json":
-            parsed["json"] = True
-            index += 1
-            continue
-        if arg == "--sessions":
-            value, index = _read_option_value(args, index, IMPORT_USAGE)
-            parsed["session_names"] = _parse_session_names(value)
-            continue
-        if arg.startswith("--sessions="):
-            parsed["session_names"] = _parse_session_names(arg.split("=", 1)[1])
-            index += 1
-            continue
-        if arg == "--passphrase-env":
-            value, index = _read_option_value(args, index, IMPORT_USAGE)
-            parsed["passphrase_env"] = value
-            continue
-        if arg.startswith("--passphrase-env="):
-            parsed["passphrase_env"] = arg.split("=", 1)[1]
-            index += 1
-            continue
-        if arg.startswith("-"):
-            raise CdxError(IMPORT_USAGE)
-        if parsed["file_path"] is not None:
-            raise CdxError(IMPORT_USAGE)
-        parsed["file_path"] = arg
-        index += 1
-
+    parsed = _parse_flag_args(args, {
+        "--force": {"key": "force", "type": "bool", "default": False},
+        "--json": {"key": "json", "type": "bool", "default": False},
+        "--sessions": {
+            "key": "session_names",
+            "type": "str",
+            "default": None,
+            "transform": _parse_session_names,
+        },
+        "--passphrase-env": {"key": "passphrase_env", "type": "str", "default": None},
+    }, IMPORT_USAGE, positionals_key="positionals", max_positionals=1)
+    parsed["file_path"] = parsed.pop("positionals")[0] if parsed["positionals"] else None
     if not parsed["file_path"]:
         raise CdxError(IMPORT_USAGE)
     return parsed
@@ -551,21 +517,20 @@ def handle_doctor(rest, ctx):
 
 
 def handle_repair(rest, ctx):
-    json_flag = "--json" in rest
-    dry_run = "--dry-run" in rest or "--force" not in rest
-    force = "--force" in rest
-    allowed = {"--json", "--dry-run", "--force"}
-    unknown = [arg for arg in rest if arg not in allowed]
-    if unknown:
-        raise CdxError(REPAIR_USAGE)
+    parsed = _parse_flag_args(rest, {
+        "--json": {"key": "json", "type": "bool", "default": False},
+        "--dry-run": {"key": "dry_run", "type": "bool", "default": False},
+        "--force": {"key": "force", "type": "bool", "default": False},
+    }, REPAIR_USAGE)
+    dry_run = parsed["dry_run"] or not parsed["force"]
     report = repair_health(
         ctx["service"],
         ctx["service"]["base_dir"],
         env=ctx.get("env"),
         dry_run=dry_run,
-        force=force,
+        force=parsed["force"],
     )
-    if json_flag:
+    if parsed["json"]:
         _write_json(ctx, _json_success("repair", "Collected repair report", report=report))
     else:
         ctx["out"](f"{format_repair_report(report, use_color=ctx['use_color'])}\n")
@@ -697,22 +662,23 @@ def handle_context(rest, ctx):
 
 
 def handle_status(rest, ctx):
-    json_flag = "--json" in rest
-    small_flag = "--small" in rest or "-s" in rest
-    refresh_flag = "--refresh" in rest
-    status_flags = {"--json", "--small", "-s", "--refresh"}
-    args = [a for a in rest if a not in status_flags]
-    unknown_flags = [a for a in args if a.startswith("-")]
-    if unknown_flags or (json_flag and small_flag):
+    parsed = _parse_flag_args(rest, {
+        "--json": {"key": "json", "type": "bool", "default": False},
+        "--small": {"key": "small", "type": "bool", "default": False},
+        "-s": {"key": "small", "type": "bool", "default": False},
+        "--refresh": {"key": "refresh", "type": "bool", "default": False},
+    }, STATUS_USAGE, positionals_key="args", max_positionals=1)
+    if parsed["json"] and parsed["small"]:
         raise CdxError(STATUS_USAGE)
-    if len(args) > 1 or (len(args) == 1 and small_flag):
+    args = parsed["args"]
+    if len(args) == 1 and parsed["small"]:
         raise CdxError(STATUS_USAGE)
 
     refresh_result = _refresh_claude_sessions(
         ctx["service"],
         ctx.get("refresh_fn"),
         target_names=args if len(args) == 1 else None,
-        force=refresh_flag,
+        force=parsed["refresh"],
     )
     refresh_errors = [
         {
@@ -732,17 +698,17 @@ def handle_status(rest, ctx):
 
     rows = ctx["service"]["get_status_rows"]()
     if len(args) == 0:
-        if json_flag:
+        if parsed["json"]:
             _write_json(ctx, _json_success("status", "Collected session status rows", warnings=warnings, rows=rows))
             return 0
-        ctx["out"](f"{_format_status_rows(rows, use_color=ctx['use_color'], small=small_flag)}\n")
+        ctx["out"](f"{_format_status_rows(rows, use_color=ctx['use_color'], small=parsed['small'])}\n")
         _write_refresh_warnings(refresh_errors, ctx)
         return 0
 
     row = next((r for r in rows if r["session_name"] == args[0]), None)
     if not row:
         raise CdxError(f"Unknown session: {args[0]}")
-    if json_flag:
+    if parsed["json"]:
         _write_json(ctx, _json_success("status", f"Collected status for {args[0]}", warnings=warnings, session=row))
         return 0
     ctx["out"](f"{_format_status_detail(row, use_color=ctx['use_color'])}\n")
@@ -995,7 +961,7 @@ def handle_launch(command, ctx, initial_prompt=None):
             if update_notice.get("url"):
                 text = f"{text} {update_notice['url']}"
             ctx["out"](f"{_warn(text, ctx['use_color'])}\n")
-    if session["provider"] == "codex":
+    if session["provider"] == PROVIDER_CODEX:
         if not json_flag:
             ctx["out"](f"{_dim('Tip: cdx status reads Codex rate limits from the local app-server when available.', ctx['use_color'])}\n")
     _run_interactive_provider_command(
@@ -1017,18 +983,19 @@ def handle_handoff(rest, ctx):
         if not session:
             raise CdxError(f"Unknown session: {name}")
         install = install_context_for_session(ctx["service"]["base_dir"], session, ctx.get("cwd"))
+        launch_prompt = _handoff_launch_prompt(session, install)
         if json_flag:
             _write_json(ctx, _json_success(
                 "handoff",
                 f"Installed shared context for {name}",
                 context=install,
-                launch_prompt=_handoff_launch_prompt(),
+                launch_prompt=launch_prompt,
                 session=session,
             ))
             return 0
         text = f"Shared context installed for {name}: {install['target_path']}"
         ctx["out"](f"{_info(text, ctx['use_color'])}\n")
-        return handle_launch(name, ctx, initial_prompt=_handoff_launch_prompt())
+        return handle_launch(name, ctx, initial_prompt=launch_prompt)
 
     source_name, target_name = args
     if source_name == target_name:
@@ -1039,8 +1006,6 @@ def handle_handoff(rest, ctx):
     target = ctx["service"]["get_session"](target_name)
     if not target:
         raise CdxError(f"Unknown session: {target_name}")
-    if source["provider"] != target["provider"]:
-        raise CdxError("Source and target sessions must use the same provider for handoff.")
     transcript_path = _latest_launch_transcript_path(source)
     if not transcript_path:
         raise CdxError(f"No launch transcript found for session: {source_name}")
@@ -1048,6 +1013,7 @@ def handle_handoff(rest, ctx):
     context = _build_handoff_context(source, target, transcript_path, transcript, truncated=truncated)
     write_result = write_context(ctx["service"]["base_dir"], context, ctx.get("cwd"))
     install = install_context_for_session(ctx["service"]["base_dir"], target, ctx.get("cwd"))
+    launch_prompt = _handoff_launch_prompt(target, install)
     if json_flag:
         _write_json(ctx, _json_success(
             "handoff",
@@ -1057,9 +1023,9 @@ def handle_handoff(rest, ctx):
             target_session=target,
             source_transcript=transcript_path,
             shared_context=write_result,
-            launch_prompt=_handoff_launch_prompt(),
+            launch_prompt=launch_prompt,
         ))
         return 0
     text = f"Handoff prepared from {source_name} to {target_name}: {install['target_path']}"
     ctx["out"](f"{_info(text, ctx['use_color'])}\n")
-    return handle_launch(target_name, ctx, initial_prompt=_handoff_launch_prompt())
+    return handle_launch(target_name, ctx, initial_prompt=launch_prompt)

package/src/codex_usage.py

@@ -106,10 +106,10 @@ def _write_json_line(process, payload):
     process.stdin.flush()
 
 
-def fetch_codex_rate_limits(session, timeout=5, popen_factory=None):
+def fetch_codex_rate_limit_diagnostic(session, timeout=5, popen_factory=None):
     auth_home = session.get("authHome")
     if not auth_home:
-        return None
+        return {"ok": False, "reason": "missing_auth_home", "status": None}
 
     env = os.environ.copy()
     env["CODEX_HOME"] = auth_home
@@ -139,7 +139,12 @@ def fetch_codex_rate_limits(session, timeout=5, popen_factory=None):
         })
         initialized = _read_response(output, 1, timeout)
         if not initialized or initialized.get("error"):
-            return None
+            return {
+                "ok": False,
+                "reason": "initialize_failed",
+                "status": None,
+                "response": initialized,
+            }
 
         _write_json_line(process, {
             "jsonrpc": "2.0",
@@ -149,13 +154,28 @@ def fetch_codex_rate_limits(session, timeout=5, popen_factory=None):
         })
         response = _read_response(output, 2, timeout)
         if not response or response.get("error"):
-            return None
+            return {
+                "ok": False,
+                "reason": "rate_limits_read_failed",
+                "status": None,
+                "response": response,
+            }
         result = response.get("result") or {}
         by_limit = result.get("rateLimitsByLimitId") or {}
         snapshot = by_limit.get("codex") or result.get("rateLimits")
-        return normalize_codex_rate_limit_snapshot(snapshot)
-    except (OSError, ValueError, BrokenPipeError):
-        return None
+        status = normalize_codex_rate_limit_snapshot(snapshot)
+        if not status:
+            return {
+                "ok": False,
+                "reason": "missing_rate_limits",
+                "status": None,
+                "response": response,
+            }
+        return {"ok": True, "reason": None, "status": status, "response": response}
+    except FileNotFoundError as error:
+        return {"ok": False, "reason": "codex_cli_not_found", "status": None, "error": str(error)}
+    except (OSError, ValueError, BrokenPipeError) as error:
+        return {"ok": False, "reason": "probe_failed", "status": None, "error": str(error)}
     finally:
         if process is not None:
             try:
@@ -166,3 +186,12 @@ def fetch_codex_rate_limits(session, timeout=5, popen_factory=None):
                     process.kill()
                 except OSError:
                     pass
+
+
+def fetch_codex_rate_limits(session, timeout=5, popen_factory=None):
+    diagnostic = fetch_codex_rate_limit_diagnostic(
+        session,
+        timeout=timeout,
+        popen_factory=popen_factory,
+    )
+    return diagnostic.get("status") if diagnostic.get("ok") else None

package/src/config.py

@@ -1,6 +1,10 @@
 import os
 from pathlib import Path
 
+PROVIDER_CODEX = "codex"
+PROVIDER_CLAUDE = "claude"
+PROVIDERS = (PROVIDER_CODEX, PROVIDER_CLAUDE)
+
 
 def get_cdx_home(env=None):
     if env is None:

package/src/notify.py

@@ -29,6 +29,13 @@ def parse_notify_args(args):
                 raise CdxError("--poll must be a number of seconds") from error
             i += 2
             continue
+        if arg.startswith("--poll="):
+            try:
+                poll = max(1, int(arg.split("=", 1)[1]))
+            except ValueError as error:
+                raise CdxError("--poll must be a number of seconds") from error
+            i += 1
+            continue
         if arg.startswith("-"):
             raise CdxError("Usage: cdx notify <name> --at-reset [--poll seconds] [--once] | cdx notify --next-ready [--poll seconds] [--once]")
         cleaned.append(arg)
@@ -121,7 +128,24 @@ def send_desktop_notification(title, message, spawn_sync=None, env=None):
         _send_windows_notification(title, message, spawn_sync, env)
     elif shutil_which("osascript", env):
         script = f'display notification "{_escape_applescript(message)}" with title "{_escape_applescript(title)}"'
-        spawn_sync(["osascript", "-e", script], env=env, capture_output=True, text=True)
+        _run_notification_command(
+            ["osascript", "-e", script],
+            spawn_sync,
+            env,
+        )
+    elif shutil_which("notify-send", env):
+        _run_notification_command(
+            ["notify-send", str(title), str(message)],
+            spawn_sync,
+            env,
+        )
+
+
+def _run_notification_command(argv, spawn_sync, env):
+    try:
+        spawn_sync(argv, env=env, capture_output=True, text=True, timeout=5)
+    except (FileNotFoundError, OSError):
+        pass
 
 
 def _send_windows_notification(title, message, spawn_sync, env):

package/src/provider_runtime.py

@@ -7,6 +7,7 @@ import subprocess
 import sys
 from datetime import datetime, timezone
 
+from .config import PROVIDER_CLAUDE, PROVIDER_CODEX
 from .errors import CdxError
 
 
@@ -99,19 +100,27 @@ def _wrap_launch_with_transcript(session, spec, capture_transcript=True, env=Non
 
 
 def _build_launch_spec(session, cwd=None, env_override=None, initial_prompt=None):
+    if initial_prompt is not None:
+        if not isinstance(initial_prompt, str):
+            raise CdxError("initial_prompt must be a string.")
+        if len(initial_prompt) > 32768:
+            raise CdxError("initial_prompt exceeds maximum allowed length.")
     cwd = cwd or os.getcwd()
     env_override = env_override or {}
     env = {**os.environ, **env_override}
-    if session["provider"] == "claude":
-        return {
+    if session["provider"] == PROVIDER_CLAUDE:
+        args = ["--name", session["name"]]
+        if initial_prompt:
+            args.append(initial_prompt)
+        return _wrap_launch_with_transcript(session, {
             "command": "claude",
-            "args": ["--name", session["name"]],
+            "args": args,
             "options": {
                 "cwd": cwd,
                 "env": {**env, **_home_env_overrides(_get_auth_home(session))},
             },
             "label": "claude",
-        }
+        }, env=env)
     args = ["--no-alt-screen", "--cd", cwd]
     if initial_prompt:
         args.append(initial_prompt)
@@ -127,7 +136,7 @@ def _build_launch_spec(session, cwd=None, env_override=None, initial_prompt=None
 
 def _build_login_status_spec(session, env_override=None):
     env = {**os.environ, **(env_override or {})}
-    if session["provider"] == "claude":
+    if session["provider"] == PROVIDER_CLAUDE:
         env.update(_home_env_overrides(_get_auth_home(session)))
 
         def parser(output):
@@ -152,7 +161,7 @@ def _build_login_status_spec(session, env_override=None):
 def _build_auth_action_spec(session, action, cwd=None, env_override=None):
     cwd = cwd or os.getcwd()
     env = {**os.environ, **(env_override or {})}
-    if session["provider"] == "claude":
+    if session["provider"] == PROVIDER_CLAUDE:
         env.update(_home_env_overrides(_get_auth_home(session)))
         return {"command": "claude", "args": ["auth", action],
                 "options": {"cwd": cwd, "env": env}, "label": f"claude auth {action}"}
@@ -181,7 +190,7 @@ def _resolve_command(command, env=None):
 def _probe_provider_auth(session, spawn_sync=None, env_override=None):
     spawn_sync = spawn_sync or subprocess.run
     spec = _build_login_status_spec(session, env_override)
-    if session.get("provider") == "codex":
+    if session.get("provider") == PROVIDER_CODEX:
         auth_path = os.path.join(_get_auth_home(session), "auth.json")
         if os.path.isfile(auth_path):
             return True
@@ -247,11 +256,12 @@ def _run_interactive_provider_command(session, action, spawn=None, cwd=None,
         spec = _fallback_launch_spec_or_raise(spec, error)
         child = start_child(spec)
 
-    forwarded_signal = [None]
+    forwarded_signal = None
     handlers = []
 
     def forward(sig, _frame=None):
-        forwarded_signal[0] = sig
+        nonlocal forwarded_signal
+        forwarded_signal = sig
         try:
             if hasattr(child, "send_signal"):
                 child.send_signal(sig)
@@ -280,7 +290,7 @@ def _run_interactive_provider_command(session, action, spawn=None, cwd=None,
 
     try:
         child.wait()
-        if forwarded_signal[0] is None and child.returncode != 0 and _should_retry_without_transcript(spec):
+        if forwarded_signal is None and child.returncode != 0 and _should_retry_without_transcript(spec):
             spec = _fallback_launch_spec_or_raise(spec)
             child = start_child(spec)
             child.wait()
@@ -298,10 +308,10 @@ def _run_interactive_provider_command(session, action, spawn=None, cwd=None,
                 except (OSError, ValueError):
                     pass
 
-    if forwarded_signal[0] is not None:
+    if forwarded_signal is not None:
         raise CdxError(
-            f"{spec['label']} interrupted by {_signal_name(forwarded_signal[0])} for session {session['name']}",
-            _signal_exit_code(forwarded_signal[0]),
+            f"{spec['label']} interrupted by {_signal_name(forwarded_signal)} for session {session['name']}",
+            _signal_exit_code(forwarded_signal),
         )
     if child.returncode != 0:
         raise CdxError(

package/src/session_service.py

@@ -8,14 +8,14 @@ from datetime import datetime, timezone
 from urllib.parse import quote
 
 from .backup_bundle import decode_bundle, encode_bundle
-from .config import get_cdx_home
+from .config import PROVIDER_CLAUDE, PROVIDER_CODEX, PROVIDERS, get_cdx_home
 from .codex_usage import fetch_codex_rate_limits
 from .errors import CdxError
 from .session_store import create_session_store
 from .status_source import find_latest_status_artifact
 
-DEFAULT_PROVIDER = "codex"
-ALLOWED_PROVIDERS = {"codex", "claude"}
+DEFAULT_PROVIDER = PROVIDER_CODEX
+ALLOWED_PROVIDERS = set(PROVIDERS)
 MAX_SESSION_NAME_LENGTH = 64
 RESERVED_SESSION_NAMES = {
     "add",
@@ -81,8 +81,15 @@ def _local_now_iso():
 
 
 def _safe_relpath(path):
-    normalized = str(path or "").replace("\\", "/").strip("/")
-    if not normalized or normalized.startswith("../") or "/../" in f"/{normalized}/":
+    normalized = os.path.normpath(str(path or "").replace("\\", "/")).replace("\\", "/")
+    if (
+        not normalized
+        or normalized == "."
+        or normalized.startswith("/")
+        or (len(normalized) > 1 and normalized[1] == ":")
+        or normalized == ".."
+        or normalized.startswith("../")
+    ):
         raise CdxError("Bundle contains an unsafe file path.")
     return normalized
 
@@ -253,7 +260,7 @@ def create_session_service(options=None):
 
     def _get_session_auth_home(name, provider):
         root = _get_session_root(name)
-        if provider == "claude":
+        if provider == PROVIDER_CLAUDE:
             return os.path.join(root, "claude-home")
         return root
 
@@ -326,7 +333,7 @@ def create_session_service(options=None):
         _ensure_private_dir(os.path.join(base_dir, "profiles"))
         _ensure_private_dir(session_root)
         _ensure_private_dir(auth_home)
-        if normalized_provider == "codex":
+        if normalized_provider == PROVIDER_CODEX:
             _seed_codex_auth_from_global(auth_home, env=env)
         now = _local_now_iso()
         session = {
@@ -553,7 +560,7 @@ def create_session_service(options=None):
         source_root = session.get("authHome") or _get_session_auth_home(
             session["name"], session["provider"]
         )
-        if session["provider"] == "codex" and codex_status_fetcher:
+        if session["provider"] == PROVIDER_CODEX and codex_status_fetcher:
             live_status = codex_status_fetcher({**session, "authHome": source_root})
             if live_status:
                 record_status(session["name"], live_status)
@@ -561,7 +568,7 @@ def create_session_service(options=None):
 
         expected_account_email = (
             _read_expected_account_email(source_root)
-            if session["provider"] == "codex"
+            if session["provider"] == PROVIDER_CODEX
             else None
         )
         artifact = find_latest_status_artifact(
@@ -570,7 +577,7 @@ def create_session_service(options=None):
             expected_account_email=expected_account_email,
         )
         if (
-            session["provider"] == "codex"
+            session["provider"] == PROVIDER_CODEX
             and not artifact
             and os.path.abspath(base_dir) == os.path.abspath(get_cdx_home(env))
         ):

package/src/status_source.py

@@ -3,6 +3,7 @@ import os
 import re
 from datetime import datetime, timezone
 
+from .config import PROVIDER_CLAUDE, PROVIDER_CODEX
 
 _ANSI_ESCAPE = re.compile(r"\x1b\[[0-9;]*m")
 _ANSI_TERMINAL_CONTROL = re.compile(r"\x1b\[[0-9;?]*[ -/]*[@-~]")
@@ -14,6 +15,23 @@ MONTH_ABBR = ["Jan", "Feb", "Mar", "Apr", "May", "Jun",
 MAX_STATUS_READ_BYTES = 512 * 1024
 MAX_STATUS_CANDIDATE_FILES = 64
 
+_KEY_VALUE_PATTERNS = [
+    ("usage_pct", re.compile(r"usage_pct\s*[:=]\s*(\d{1,3})%?", re.I)),
+    ("remaining_5h_pct", re.compile(r"remaining_?5h_pct\s*[:=]\s*(\d{1,3})%?", re.I)),
+    ("remaining_week_pct", re.compile(r"remaining_?week_pct\s*[:=]\s*(\d{1,3})%?", re.I)),
+    ("credits", re.compile(r"credits?\s*[:=]\s*([\d, ]*\d[\d, ]*)\s*(?:credits?)?", re.I)),
+    ("remaining_5h_pct", re.compile(r"5h\s+limit\s*:\s*\[[^\]]*\]\s*(\d{1,3})%\s*left", re.I)),
+    ("remaining_week_pct", re.compile(r"weekly\s+limit\s*:\s*\[[^\]]*\]\s*(\d{1,3})%\s*left", re.I)),
+    ("remaining_5h_pct", re.compile(r"5h\s+limit\s*:\s*\[[^\]]*\]\s*(\d{1,3})(?:%|\b)", re.I)),
+    ("remaining_week_pct", re.compile(r"weekly\s+limit\s*:\s*\[[^\]]*\]\s*(\d{1,3})(?:%|\b)", re.I)),
+    ("usage_pct", re.compile(r"usage\s*[:=]\s*(\d{1,3})%", re.I)),
+    ("usage_pct", re.compile(r"current\s*[:=]\s*(\d{1,3})%", re.I)),
+    ("remaining_5h_pct", re.compile(r"5h(?:\s+remaining)?\s*[:=]\s*(\d{1,3})%", re.I)),
+    ("remaining_5h_pct", re.compile(r"remaining\s+5h\s*[:=]\s*(\d{1,3})%", re.I)),
+    ("remaining_week_pct", re.compile(r"week(?:\s+remaining)?\s*[:=]\s*(\d{1,3})%", re.I)),
+    ("remaining_week_pct", re.compile(r"remaining\s+week\s*[:=]\s*(\d{1,3})%", re.I)),
+]
+
 
 def _strip_ansi(text):
     return _ANSI_ESCAPE.sub("", str(text or ""))
@@ -185,7 +203,7 @@ def _extract_status_blocks_from_text(text, provider=None, source_ref=None, times
             index = max(index + 1, end_index)
         return blocks
 
-    if provider != "codex":
+    if provider != PROVIDER_CODEX:
         for block in collect_blocks(
             re.compile(r"^\s*(?:[│|]\s*)?Current session\b", re.I),
             [re.compile(p, re.I) for p in [
@@ -195,7 +213,7 @@ def _extract_status_blocks_from_text(text, provider=None, source_ref=None, times
         ):
             items.append({"source_ref": source_ref, "timestamp": timestamp, "text": block})
 
-    if provider != "claude":
+    if provider != PROVIDER_CLAUDE:
         for block in collect_blocks(
             re.compile(r"^\s*(?:[│|]\s*)?5h\s+limit\b", re.I),
             [re.compile(p, re.I) for p in [
@@ -412,23 +430,7 @@ def extract_named_statuses_from_text(text):
     lines = [l.strip() for l in normalized.split("\n") if l.strip()]
     result = {}
 
-    key_value_patterns = [
-        ("usage_pct", re.compile(r"usage_pct\s*[:=]\s*(\d{1,3})%?", re.I)),
-        ("remaining_5h_pct", re.compile(r"remaining_?5h_pct\s*[:=]\s*(\d{1,3})%?", re.I)),
-        ("remaining_week_pct", re.compile(r"remaining_?week_pct\s*[:=]\s*(\d{1,3})%?", re.I)),
-        ("credits", re.compile(r"credits?\s*[:=]\s*([\d, ]*\d[\d, ]*)\s*(?:credits?)?", re.I)),
-        ("remaining_5h_pct", re.compile(r"5h\s+limit\s*:\s*\[[^\]]*\]\s*(\d{1,3})%\s*left", re.I)),
-        ("remaining_week_pct", re.compile(r"weekly\s+limit\s*:\s*\[[^\]]*\]\s*(\d{1,3})%\s*left", re.I)),
-        ("remaining_5h_pct", re.compile(r"5h\s+limit\s*:\s*\[[^\]]*\]\s*(\d{1,3})(?:%|\b)", re.I)),
-        ("remaining_week_pct", re.compile(r"weekly\s+limit\s*:\s*\[[^\]]*\]\s*(\d{1,3})(?:%|\b)", re.I)),
-        ("usage_pct", re.compile(r"usage\s*[:=]\s*(\d{1,3})%", re.I)),
-        ("usage_pct", re.compile(r"current\s*[:=]\s*(\d{1,3})%", re.I)),
-        ("remaining_5h_pct", re.compile(r"5h(?:\s+remaining)?\s*[:=]\s*(\d{1,3})%", re.I)),
-        ("remaining_5h_pct", re.compile(r"remaining\s+5h\s*[:=]\s*(\d{1,3})%", re.I)),
-        ("remaining_week_pct", re.compile(r"week(?:\s+remaining)?\s*[:=]\s*(\d{1,3})%", re.I)),
-        ("remaining_week_pct", re.compile(r"remaining\s+week\s*[:=]\s*(\d{1,3})%", re.I)),
-    ]
-    for field, pattern in key_value_patterns:
+    for field, pattern in _KEY_VALUE_PATTERNS:
         if field not in result:
             m = pattern.search(normalized)
             if m:
@@ -620,7 +622,7 @@ def find_latest_status_artifact(root_dir, provider=None, expected_account_email=
 
     best = None
     for candidate in records:
-        if provider == "codex" and not _account_matches_expected(
+        if provider == PROVIDER_CODEX and not _account_matches_expected(
             candidate["text"], expected_account_email
         ):
             continue