cdx-manager 0.20.9 → 0.20.11

package/src/cli_helpers.py

@@ -12,15 +12,11 @@ import re
 from datetime import datetime
 
 from .cli_render import _dim, _info, _pad_table, _style, _warn
-from .config import PROVIDER_CODEX
 from .errors import CdxError
 from .fs_utils import atomic_write
-from .provider_runtime import _list_launch_transcript_paths, _run_interactive_provider_command, get_resume_capability
-from .status_source import _normalize_terminal_transcript
+from .provider_runtime import _run_interactive_provider_command, get_resume_capability
 
 API_SCHEMA_VERSION = 1
-HANDOFF_TRANSCRIPT_CHARS = 120000
-HANDOFF_NATIVE_TRANSCRIPT_CANDIDATES = 64
 
 
 def _local_now_iso():
@@ -201,213 +197,6 @@ def _make_notify_progress(ctx):
     )
 
 
-def _latest_launch_transcript_path(session):
-    paths = _list_launch_transcript_paths(session)
-    if not paths:
-        return None
-    return max(paths, key=lambda path: (os.path.getmtime(path), path))
-
-
-def _get_session_home(session):
-    return session.get("authHome") or session.get("sessionRoot") or session.get("codexHome", "")
-
-
-def _safe_stat(path):
-    try:
-        return os.stat(path)
-    except OSError:
-        return None
-
-
-def _sort_recent_paths(paths):
-    stats = {path: stat for path, stat in ((_path, _safe_stat(_path)) for _path in set(paths)) if stat}
-    return sorted(stats, key=lambda path: (stats[path].st_mtime, path), reverse=True)
-
-
-def _collect_native_handoff_transcript_paths(session):
-    root = _get_session_home(session)
-    if not root:
-        return []
-    candidates = []
-    direct = [
-        os.path.join(root, "history.jsonl"),
-        os.path.join(root, "session_index.jsonl"),
-    ]
-    candidates.extend(path for path in direct if _safe_stat(path))
-
-    scan_roots = [
-        os.path.join(root, "sessions"),
-        os.path.join(root, ".claude", "projects"),
-        os.path.join(root, "projects"),
-    ]
-    skip_dirs = {"cache", "plugins", "skills", "memories", "sqlite", "shell_snapshots", "tmp", "__pycache__"}
-    for scan_root in scan_roots:
-        if not os.path.isdir(scan_root):
-            continue
-        for dirpath, dirnames, filenames in os.walk(scan_root):
-            dirnames[:] = [name for name in dirnames if not name.startswith(".") and name not in skip_dirs]
-            for filename in filenames:
-                if filename.endswith(".jsonl") or filename.endswith(".log"):
-                    candidates.append(os.path.join(dirpath, filename))
-    return _sort_recent_paths(candidates)[:HANDOFF_NATIVE_TRANSCRIPT_CANDIDATES]
-
-
-def _handoff_transcript_workspace(path):
-    if not path.endswith(".jsonl"):
-        return None
-    try:
-        with open(path, encoding="utf-8", errors="replace") as handle:
-            record = json.loads(handle.readline() or "{}")
-    except (OSError, json.JSONDecodeError):
-        return None
-    if record.get("type") != "session_meta":
-        return None
-    payload = record.get("payload") if isinstance(record.get("payload"), dict) else {}
-    cwd = payload.get("cwd")
-    return os.path.realpath(cwd) if isinstance(cwd, str) and cwd else None
-
-
-def _latest_handoff_transcript_path(session, cwd=None):
-    native_paths = _collect_native_handoff_transcript_paths(session)
-    if cwd:
-        workspace = os.path.realpath(cwd)
-        for path in native_paths:
-            if _handoff_transcript_workspace(path) == workspace:
-                return path
-    if native_paths:
-        return native_paths[0]
-    return _latest_launch_transcript_path(session)
-
-
-def _collect_handoff_text_fragments(value):
-    fragments = []
-    if isinstance(value, str):
-        text = value.strip()
-        if text:
-            fragments.append(text)
-    elif isinstance(value, list):
-        for item in value:
-            fragments.extend(_collect_handoff_text_fragments(item))
-    elif isinstance(value, dict):
-        if isinstance(value.get("text"), str):
-            fragments.extend(_collect_handoff_text_fragments(value.get("text")))
-        if isinstance(value.get("content"), (str, list, dict)):
-            fragments.extend(_collect_handoff_text_fragments(value.get("content")))
-        if isinstance(value.get("message"), dict):
-            fragments.extend(_collect_handoff_text_fragments(value.get("message")))
-        if isinstance(value.get("payload"), dict):
-            fragments.extend(_collect_handoff_text_fragments(value.get("payload")))
-    return fragments
-
-
-def _jsonl_record_to_handoff_text(record):
-    if not isinstance(record, dict):
-        return None
-    if record.get("type") == "response_item":
-        record = record.get("payload")
-        if not isinstance(record, dict):
-            return None
-    message = record.get("message") if isinstance(record.get("message"), dict) else {}
-    role = (
-        message.get("role")
-        or record.get("role")
-        or record.get("type")
-        or record.get("sender")
-        or "entry"
-    )
-    if role not in ("user", "assistant"):
-        return None
-    text_sources = []
-    for key in ("content", "text", "payload"):
-        if key in record:
-            text_sources.append(record.get(key))
-    for key in ("content", "text"):
-        if key in message:
-            text_sources.append(message.get(key))
-    fragments = []
-    for value in text_sources:
-        fragments.extend(_collect_handoff_text_fragments(value))
-    text = "\n".join(fragment for fragment in fragments if fragment).strip()
-    if not text:
-        return None
-    role = re.sub(r"[^A-Za-z0-9_-]+", "-", str(role).strip()).strip("-") or "entry"
-    return f"[{role}]\n{text}"
-
-
-def _read_jsonl_handoff_transcript(path):
-    entries = []
-    with open(path, encoding="utf-8", errors="replace") as handle:
-        for line in handle:
-            line = line.strip()
-            if not line:
-                continue
-            try:
-                text = _jsonl_record_to_handoff_text(json.loads(line))
-            except json.JSONDecodeError:
-                text = None
-            if text:
-                entries.append(text)
-    if entries:
-        return "\n\n".join(entries)
-    with open(path, encoding="utf-8", errors="replace") as handle:
-        return handle.read()
-
-
-def _read_handoff_transcript(path):
-    if path.endswith(".jsonl"):
-        content = _read_jsonl_handoff_transcript(path)
-    else:
-        with open(path, encoding="utf-8", errors="replace") as handle:
-            # `script`-captured PTY transcript: strip ANSI/control noise before
-            # the char-budget truncation so the tail holds real text, not escapes.
-            content = _normalize_terminal_transcript(handle.read())
-    if len(content) <= HANDOFF_TRANSCRIPT_CHARS:
-        return content, False
-    return content[-HANDOFF_TRANSCRIPT_CHARS:], True
-
-
-def _build_handoff_context(source, target, transcript_path, transcript, truncated=False):
-    truncation_note = (
-        "Only the tail of the previous transcript is included because the log was large."
-        if truncated else
-        "The previous transcript is included below."
-    )
-    return "\n".join([
-        "# Shared Context",
-        "",
-        "## Goal",
-        f"Resume the work from `{source['name']}` in `{target['name']}` because the source account has no usage left.",
-        "",
-        "## Current State",
-        f"- Source session: `{source['name']}` ({source['provider']})",
-        f"- Target session: `{target['name']}` ({target['provider']})",
-        f"- Transcript source: `{transcript_path}`",
-        f"- {truncation_note}",
-        "",
-        "## Previous Session Transcript",
-        transcript.rstrip(),
-        "",
-        "## Next Steps",
-        "- Read the transcript above.",
-        "- Continue the task from the latest actionable state.",
-        "- Preserve the target account authentication; do not copy source credentials.",
-    ])
-
-
-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 (
-        f"Read {context_ref} first, then resume the previous session "
-        "from the latest actionable state. Do not ask me to paste the context again."
-    )
-
-
 def _resolve_confirmation(confirm_fn, name):
     confirmed = (
         asyncio.get_event_loop().run_until_complete(confirm_fn(name))

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/launch.py

@@ -10,11 +10,8 @@ from ..agent_notify import notifications_enabled, provision, supports_agent_aler
 from ..cli_args import CAN_RESUME_USAGE, HANDOFF_USAGE, RESUME_USAGE, _parse_json_flag
 from ..cli_helpers import (
     API_SCHEMA_VERSION,
-    _build_handoff_context,
-    _handoff_launch_prompt,
+    _json_failure,
     _json_success,
-    _latest_handoff_transcript_path,
-    _read_handoff_transcript,
     _resume_capability_for_session,
     _update_notice_warnings,
     _warn_if_session_already_running,
@@ -23,8 +20,8 @@ from ..cli_helpers import (
 )
 from ..cli_render import _dim, _info, _success, _warn
 from ..config import PROVIDER_CODEX
-from ..context_store import install_context_for_session, write_context
 from ..errors import CdxError
+from ..handoff import HandoffSourceError, launch_prompt, load_entry, prepare_entry, resolve_source
 from ..interactive_usage import extract_interactive_usage, transcript_predates_run, usage_delta
 from ..provider_runtime import (
     INTERRUPT_EXIT_CODES,
@@ -397,59 +394,92 @@ def _previous_cumulative(history, transcript_path):
             return cumulative
     return None
 
-def handle_handoff(rest, ctx):
+def _parse_handoff_args(rest):
     json_flag, args = _parse_json_flag(rest)
-    if len(args) not in (1, 2):
+    names, flags = [], {}
+    index = 0
+    while index < len(args):
+        arg = args[index]
+        if arg.startswith("--"):
+            key, sep, value = arg.partition("=")
+            if key not in ("--source-conversation", "--source-transcript") or key in flags:
+                raise CdxError(HANDOFF_USAGE)
+            if not sep:
+                index += 1
+                value = args[index] if index < len(args) else ""
+            if not value or value.startswith("--"):
+                raise CdxError(HANDOFF_USAGE)
+            flags[key] = value
+        else:
+            names.append(arg)
+        index += 1
+    if len(names) not in (1, 2) or (flags and len(names) != 2) or len(flags) > 1:
         raise CdxError(HANDOFF_USAGE)
-    if len(args) == 1:
-        name = args[0]
-        session = ctx["service"]["get_session"](name)
-        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=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=launch_prompt)
-
-    source_name, target_name = args
-    if source_name == target_name:
-        raise CdxError("Source and target sessions must be different")
-    source = ctx["service"]["get_session"](source_name)
-    if not source:
-        raise CdxError(f"Unknown session: {source_name}")
-    target = ctx["service"]["get_session"](target_name)
+    return json_flag, names, flags
+
+
+def _handoff_source(source, workspace, flags, ctx, json_flag):
+    try:
+        return resolve_source(source, workspace, flags.get("--source-conversation"), flags.get("--source-transcript"))
+    except HandoffSourceError as error:
+        candidates = error.candidates
+        # JSON and non-interactive callers always make an explicit second call.
+        if json_flag or not ctx["stdin_is_tty"] or not candidates or flags:
+            raise
+        ctx["out"](str(error) + "\n" + "".join(
+            f"  {i + 1}. {c['conversation_id']} | {c['workspace']} | last event {c['last_event_at'] or 'unknown'}\n"
+            for i, c in enumerate(candidates)
+        ))
+        ask = ctx["options"].get("input") or input
+        try:
+            answer = ask("Source conversation number (blank to cancel): ").strip()
+        except (KeyboardInterrupt, EOFError):
+            raise CdxError("Handoff cancelled.", exit_code=130) from None
+        if not answer:
+            raise CdxError("Handoff cancelled.", exit_code=130) from None
+        if not answer.isdigit() or not 1 <= int(answer) <= len(candidates):
+            raise CdxError("Handoff cancelled: choose a listed source.") from None
+        return resolve_source(source, workspace, candidates[int(answer) - 1]["conversation_id"])
+
+
+def handle_handoff(rest, ctx):
+    json_flag, names, flags = _parse_handoff_args(rest)
+    target = ctx["service"]["get_session"](names[-1])
     if not target:
-        raise CdxError(f"Unknown session: {target_name}")
-    transcript_path = _latest_handoff_transcript_path(source, ctx.get("cwd"))
-    if not transcript_path:
-        raise CdxError(f"No transcript found for session: {source_name}")
-    transcript, truncated = _read_handoff_transcript(transcript_path)
-    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)
+        raise CdxError(f"Unknown session: {names[-1]}")
+    if not target.get("enabled", True):
+        raise CdxError(f"Session is disabled: {target['name']}")
+    workspace = os.path.realpath(ctx.get("cwd") or os.getcwd())
+    if not os.path.isdir(workspace):
+        raise CdxError(f"Invalid directory: {workspace}")
+    base_dir = ctx["service"]["base_dir"]
+    source = None
+    if len(names) == 2:
+        if names[0] == names[1]:
+            raise CdxError("Source and target sessions must be different")
+        source = ctx["service"]["get_session"](names[0])
+        if not source:
+            raise CdxError(f"Unknown session: {names[0]}")
+        try:
+            transcript = _handoff_source(source, workspace, flags, ctx, json_flag)
+        except HandoffSourceError as error:
+            if not json_flag:
+                choices = "\n".join(f"  {c['conversation_id']} | {c['workspace']} | {c['last_event_at'] or 'unknown'}" for c in error.candidates)
+                raise CdxError(str(error) + ("\nCandidates:\n" + choices if choices else "")) from error
+            _write_json(ctx, _json_failure("handoff", "handoff_source_unresolved", str(error), candidates=error.candidates))
+            return error.exit_code
+        path, entry = prepare_entry(base_dir, target, workspace, source, transcript)
+    else:
+        prepared = load_entry(base_dir, target, workspace)
+        path, entry = prepared if prepared else prepare_entry(base_dir, target, workspace)
+    prompt = launch_prompt(path, entry)
     if json_flag:
         _write_json(ctx, _json_success(
-            "handoff",
-            f"Prepared handoff from {source_name} to {target_name}",
-            context=install,
-            source_session=source,
-            target_session=target,
-            source_transcript=transcript_path,
-            shared_context=write_result,
-            launch_prompt=launch_prompt,
+            "handoff", f"Prepared {entry['mode']} handoff for {target['name']}",
+            context={"target_path": path}, handoff=entry,
+            source_session=entry['source'], target_session={"name": target['name'], "provider": target['provider']},
+            source_transcript=(entry['transcript'] or {}).get('path'), launch_prompt=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=launch_prompt)
+    ctx["out"](f"Handoff ready ({entry['mode']}): {path}\n")
+    return handle_launch(target['name'], ctx, initial_prompt=prompt, directory=workspace)

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):