cdx-manager 0.21.6 → 0.23.0

package/src/cli_args.py

@@ -33,26 +33,28 @@ CONTEXT_USAGE = "Usage: cdx context show|path|init|edit|clear|set|append [text..
 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> [--source-conversation ID | --source-native-transcript PATH | --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] [--notify on|off] [--notify-preview on|off] [--scrub-env 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|--notify|--notify-preview|--scrub-env|--model|--fallback-model|--budget|--extra-args|--priority|--all) [--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] [--notify on|off] [--notify-preview on|off] [--scrub-env on|off] [--shared-memory on|off] [--retro on|off] [--policy use|ask-first|never] [--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|--notify|--notify-preview|--scrub-env|--shared-memory|--retro|--policy|--model|--fallback-model|--budget|--extra-args|--priority|--all) [--json]"
 SETTING_ALIAS_USAGE = "Usage: cdx power|perm|fast|model <name|all|provider:PROVIDER|a,b> <value|default> [--json]"
 CONFIG_USAGE = "Usage: cdx config <name> [--json]"
 CONFIGS_USAGE = "Usage: cdx configs [--json]"
 HISTORY_USAGE = "Usage: cdx history [name] [--limit N] [--summary] [--since 7d|today|DATE] [--from DATE] [--to DATE] [--json]"
-STATS_USAGE = "Usage: cdx stats [name] [--since 7d|today|DATE] [--from DATE] [--to DATE] [--json]"
+STATS_USAGE = "Usage: cdx stats [name] [--since 7d|today|DATE] [--from DATE] [--to DATE] [--by session|project|model] [--json]"
+STATS_GROUPS = ("session", "project", "model")
 LAST_USAGE = "Usage: cdx last [--json]"
-RESUME_USAGE = "Usage: cdx resume <name> [--json]"
-CAN_RESUME_USAGE = "Usage: cdx can-resume <name> [--json]"
+RESUME_USAGE = "Usage: cdx resume <name> [--conversation <id>] [--json]"
+CAN_RESUME_USAGE = "Usage: cdx can-resume <name> [--conversation <id>] [--json]"
+SESSIONS_USAGE = "Usage: cdx sessions [--all] --json"
 SELECT_USAGE = "Usage: cdx select --provider PROVIDER [--min-reasoning-effort minimal|low|medium|high|xhigh] [--min-power minimal|low|medium|high|xhigh] [--require-ready] [--refresh] --json"
 NEXT_USAGE = "Usage: cdx next [--json] [--refresh]"
-RUN_USAGE = "Usage: cdx run [session] (--cwd|--dir) PATH (--prompt-file PATH|--prompt TEXT|--prompt-file -) [--provider PROVIDER] [--model MODEL] [--kind assistant|code-review] [--reasoning-effort minimal|low|medium|high|xhigh] [--power minimal|low|medium|high|xhigh] [--permission review|default|auto|full|workspace-write|read-only|danger-full-access] [--timeout-seconds N] [--detach] [--failover] [--refresh] --json"
+RUN_USAGE = "Usage: cdx run [session] (--cwd|--dir) PATH (--prompt-file PATH|--prompt TEXT|--prompt-file -) [--provider PROVIDER] [--model MODEL] [--kind assistant|code-review|retro] [--reasoning-effort minimal|low|medium|high|xhigh] [--power minimal|low|medium|high|xhigh] [--permission review|default|auto|full|workspace-write|read-only|danger-full-access] [--timeout-seconds N] [--label TEXT] [--max-parallel N] [--detach] [--failover] [--refresh] --json"
 RUN_JSON_REQUIRED = "cdx run: --json is required."
 RUN_TARGET_REQUIRED = "cdx run: specify a session name or --provider PROVIDER."
 RUN_SESSION_PROVIDER_CONFLICT = "cdx run: cannot specify both a session name and --provider."
 RUN_CWD_REQUIRED = "cdx run: --cwd PATH is required."
 RUN_PROMPT_SOURCE_REQUIRED = "cdx run: specify exactly one prompt source: --prompt TEXT or --prompt-file PATH."
 RUN_DETACH_FAILOVER_CONFLICT = "cdx run: --failover needs to watch the run, which --detach gives up."
-RUN_KIND_VALUES = ("assistant", "code-review")
+RUN_KIND_VALUES = ("assistant", "code-review", "retro")
 # Aliases of the shared definitions in config, kept only so the existing
 # RUN_* spellings in this module keep reading naturally. They are references,
 # not copies: config.py is the single owner.
@@ -60,7 +62,7 @@ RUN_PERMISSION_VALUES = PERMISSION_INPUT_VALUES
 RUN_PERMISSION_CANONICAL_VALUES = PERMISSION_VALUES
 RUN_PERMISSION_ALIASES = PERMISSION_ALIASES
 RUN_EFFORT_VALUES = REASONING_EFFORT_VALUES
-RUNS_USAGE = "Usage: cdx runs [--limit N] [--since 7d|today|DATE] --json"
+RUNS_USAGE = "Usage: cdx runs [--limit N] [--since 7d|today|DATE] [--running] --json"
 RUN_STATUS_USAGE = "Usage: cdx run-status <run_id> --json"
 RUN_REPORT_USAGE = "Usage: cdx run-report <run_id> --json"
 RUN_TAIL_USAGE = "Usage: cdx run-tail <run_id> [--lines N] --json"
@@ -79,6 +81,28 @@ ARG_CODE_OUT_OF_RANGE = "argument_value_out_of_range"
 ARG_CODE_UNKNOWN = "unknown_argument"
 
 
+def _pop_value_flag(args, flag, usage):
+    """Remove `flag VALUE` / `flag=VALUE` from args; return (value or None, rest)."""
+    value, rest, index = None, [], 0
+    while index < len(args):
+        arg = args[index]
+        name, sep, inline = arg.partition("=")
+        if name != flag:
+            rest.append(arg)
+            index += 1
+            continue
+        if sep:
+            candidate, index = inline, index + 1
+        elif index + 1 < len(args):
+            candidate, index = args[index + 1], index + 2
+        else:
+            raise CdxError(usage)
+        if value is not None or not candidate:
+            raise CdxError(usage)
+        value = candidate
+    return value, rest
+
+
 def _parse_json_flag(args):
     json_flag = "--json" in args
     cleaned = [arg for arg in args if arg != "--json"]
@@ -253,11 +277,14 @@ def _parse_set_args(args):
         "--notify": {"key": "notify", "type": "str", "default": None, "transform": _on_off("notify")},
         "--notify-preview": {"key": "notify_preview", "type": "str", "default": None, "transform": _on_off("notify preview")},
         "--scrub-env": {"key": "scrub_env", "type": "str", "default": None, "transform": _on_off("scrub env")},
+        "--shared-memory": {"key": "shared_memory", "type": "str", "default": None, "transform": _on_off("shared memory")},
+        "--retro": {"key": "retro", "type": "str", "default": None, "transform": _on_off("retro")},
         "--model": {"key": "model", "type": "str", "default": None},
         "--fallback-model": {"key": "fallback_model", "type": "str", "default": None},
         "--budget": {"key": "budget", "type": "str", "default": None, "transform": _parse_budget_value},
         "--extra-args": {"key": "extra_args", "type": "str", "default": None},
         "--priority": {"key": "priority", "type": "str", "default": None, "transform": _parse_priority_value},
+        "--policy": {"key": "policy", "type": "str", "default": None},
         "--sessions": {"key": "sessions", "type": "str", "default": None, "transform": _parse_set_unset_sessions},
         "--provider": {"key": "provider", "type": "str", "default": None, "transform": lambda value: _parse_provider_filter(value, SET_USAGE)},
         "--json": {"key": "json", "type": "bool", "default": False},
@@ -274,7 +301,7 @@ def _parse_set_args(args):
         raise CdxError(SET_USAGE)
     settings = {
         key: parsed[key]
-        for key in ("power", "permission", "fast", "rtk", "logics", "notify", "notify_preview", "scrub_env", "model", "fallback_model", "budget", "extra_args", "priority")
+        for key in ("power", "permission", "fast", "rtk", "logics", "notify", "notify_preview", "scrub_env", "shared_memory", "retro", "model", "fallback_model", "budget", "extra_args", "priority", "policy")
         if parsed[key] is not None
     }
     if not settings:
@@ -299,11 +326,14 @@ def _parse_unset_args(args):
         "--notify": {"key": "notify", "type": "bool", "default": False},
         "--notify-preview": {"key": "notify_preview", "type": "bool", "default": False},
         "--scrub-env": {"key": "scrub_env", "type": "bool", "default": False},
+        "--shared-memory": {"key": "shared_memory", "type": "bool", "default": False},
+        "--retro": {"key": "retro", "type": "bool", "default": False},
         "--model": {"key": "model", "type": "bool", "default": False},
         "--fallback-model": {"key": "fallback_model", "type": "bool", "default": False},
         "--budget": {"key": "budget", "type": "bool", "default": False},
         "--extra-args": {"key": "extra_args", "type": "bool", "default": False},
         "--priority": {"key": "priority", "type": "bool", "default": False},
+        "--policy": {"key": "policy", "type": "bool", "default": False},
         "--all": {"key": "all", "type": "bool", "default": False},
         "--sessions": {"key": "sessions", "type": "str", "default": None, "transform": _parse_set_unset_sessions},
         "--provider": {"key": "provider", "type": "str", "default": None, "transform": lambda value: _parse_provider_filter(value, UNSET_USAGE)},
@@ -320,8 +350,8 @@ def _parse_unset_args(args):
     if not parsed["names"] and not parsed["sessions"] and not parsed["provider"]:
         raise CdxError(UNSET_USAGE)
     _UNSET_KEYS = (
-        "power", "reasoning_effort", "permission", "fast", "rtk", "logics", "notify", "notify_preview", "scrub_env",
-        "model", "fallback_model", "budget", "extra_args", "priority",
+        "power", "reasoning_effort", "permission", "fast", "rtk", "logics", "notify", "notify_preview", "scrub_env", "shared_memory", "retro",
+        "model", "fallback_model", "budget", "extra_args", "priority", "policy",
     )
     keys = list(_UNSET_KEYS) if parsed["all"] else [key for key in _UNSET_KEYS if parsed[key]]
     if not keys:
@@ -513,6 +543,9 @@ def cdx_schema():
                 "provider_failed",
                 "provider_timeout",
                 "run_cancelled",
+                "too_many_runs",
+                "failover_exhausted",
+                "failover_limit_reached",
                 "invalid_request",
                 "cdx_error",
             ],
@@ -611,6 +644,17 @@ def _parse_run_effort(reasoning_effort, power):
         ) from error
 
 
+def _parse_max_parallel(value):
+    try:
+        parsed = int(value)
+    except (TypeError, ValueError):
+        parsed = 0
+    if parsed < 1:
+        raise CdxArgumentError("cdx run: --max-parallel takes a whole number of at least 1.",
+                               code=ARG_CODE_INVALID_VALUE, arguments=["--max-parallel"])
+    return parsed
+
+
 def _parse_run_args(args):
     parsed = _parse_run_flag_args(args, {
         "--cwd": {"key": "cwd", "type": "str", "default": None},
@@ -627,6 +671,8 @@ def _parse_run_args(args):
         "--detach": {"key": "detach", "type": "bool", "default": False},
         "--failover": {"key": "failover", "type": "bool", "default": False},
         "--refresh": {"key": "refresh", "type": "bool", "default": False},
+        "--label": {"key": "label", "type": "str", "default": None},
+        "--max-parallel": {"key": "max_parallel", "type": "str", "default": None, "transform": _parse_max_parallel},
         "--json": {"key": "json", "type": "bool", "default": False},
     }, RUN_USAGE, positionals_key="names", max_positionals=1)
     if not parsed["json"]:
@@ -681,6 +727,8 @@ def _parse_run_args(args):
         "timeout_seconds": parsed["timeout_seconds"],
         "detach": parsed["detach"],
         "failover": parsed["failover"],
+        "label": parsed["label"],
+        "max_parallel": parsed["max_parallel"],
         "refresh": parsed["refresh"],
         "reasoning_effort": effort.get("reasoning_effort"),
         "power": effort.get("power"),
@@ -845,12 +893,16 @@ def _parse_stats_args(args, now=None):
         "--since": {"key": "since", "type": "str", "default": None},
         "--from": {"key": "from", "type": "str", "default": None},
         "--to": {"key": "to", "type": "str", "default": None},
+        "--by": {"key": "by", "type": "str", "default": "session"},
         "--json": {"key": "json", "type": "bool", "default": False},
     }, STATS_USAGE, positionals_key="names", max_positionals=1)
+    if parsed["by"] not in STATS_GROUPS:
+        raise CdxError(STATS_USAGE)
     period = _parse_history_period(parsed, now, STATS_USAGE)
     return {
         "name": parsed["names"][0] if parsed["names"] else None,
         "period": period,
+        "by": parsed["by"],
         "json": parsed["json"],
     }
 
@@ -1004,8 +1056,13 @@ def _parse_runs_args(rest, now=None):
     parsed = _parse_flag_args(rest, {
         "--limit": {"key": "limit", "type": "str", "default": 20, "transform": _parse_positive_int},
         "--since": {"key": "since", "type": "str", "default": None},
+        "--running": {"key": "running", "type": "bool", "default": False},
         "--json": {"key": "json", "type": "bool", "default": False},
     }, RUNS_USAGE, max_positionals=0)
+    if parsed["running"] and parsed["since"] is not None:
+        # --since returns completed runs only, --running the ones not completed:
+        # together they can only ever answer "nothing".
+        raise CdxError("cdx runs: --running and --since are mutually exclusive.")
     since = None
     if parsed["since"] is not None:
         # Same cursor forms as `cdx history --since`, parsed by the same code:
@@ -1019,6 +1076,7 @@ def _parse_runs_args(rest, now=None):
         # a watchdog behind by more than `limit` completions would never see
         # the older ones at all.
         "limit_given": any(arg == "--limit" or arg.startswith("--limit=") for arg in rest),
+        "running": parsed["running"],
         "json": parsed["json"],
     }
 

package/src/cli_commands.py

@@ -265,6 +265,9 @@ from .commands.status import (
 from .commands.status import (
     handle_next as handle_next,
 )
+from .commands.status import (
+    handle_sessions as handle_sessions,
+)
 from .commands.status import (
     handle_stats as handle_stats,
 )

package/src/cli_helpers.py

@@ -249,13 +249,23 @@ def _bootstrap_claude_setup_token(session, ctx):
     ctx["out"](
         "Minting a long-lived Claude setup-token for this session.\n"
     )
-    run_info = _run_interactive_provider_command(
-        session,
-        "setup-token",
-        spawn=ctx.get("spawn"),
-        env_override=ctx.get("env"),
-        signal_emitter=ctx.get("signal_emitter"),
-    )
+    try:
+        run_info = _run_interactive_provider_command(
+            session,
+            "setup-token",
+            spawn=ctx.get("spawn"),
+            env_override=ctx.get("env"),
+            signal_emitter=ctx.get("signal_emitter"),
+        )
+    except Exception as error:
+        # A failed or interrupted run can still have printed the token.
+        failed_path = (getattr(error, "run_info", None) or {}).get("transcript_path")
+        if failed_path:
+            try:
+                os.remove(failed_path)
+            except OSError:
+                pass
+        raise
     transcript_path = run_info.get("transcript_path")
     if not transcript_path or not os.path.isfile(transcript_path):
         raise CdxError(
@@ -304,11 +314,14 @@ def _format_launch_config(session, use_color=False):
         ("notify", "Agent alerts"),
         ("notify_preview", "Response preview"),
         ("scrub_env", "Scrub agent env"),
+        ("shared_memory", "Shared memory"),
+        ("retro", "Session retro"),
         ("model", "Model"),
         ("fallback_model", "Fallback"),
         ("budget", "Budget"),
         ("extra_args", "Extra args"),
         ("priority", "Priority"),
+        ("policy", "Policy"),
     ]:
         rows.append([
             _dim(label, use_color),
@@ -330,14 +343,14 @@ def _format_launch_settings_hint(name="<name>"):
     )
 
 def _format_launch_setting_value(launch, key, use_color=False):
-    if key in ("fast", "rtk", "logics", "notify", "notify_preview", "scrub_env"):
+    if key in ("fast", "rtk", "logics", "notify", "notify_preview", "scrub_env", "shared_memory", "retro"):
         if launch.get(key) is True:
             return _style("on", "32", use_color)
         if launch.get(key) is False:
             return _style("off", "2", use_color)
         if key == "logics":
             return _dim("auto", use_color)
-        if key in ("notify", "notify_preview", "scrub_env"):
+        if key in ("notify", "notify_preview", "scrub_env", "shared_memory", "retro"):
             return _style("off", "2", use_color)
         return _dim("default", use_color)
     value = launch.get(key)

package/src/commands/launch.py

@@ -6,8 +6,9 @@ Split out of cli_commands.py. Moved verbatim; re-exported by cli_commands.
 import os
 import shlex
 
+from .. import retro, shared_memory
 from ..agent_notify import notifications_enabled, provision, supports_agent_alerts
-from ..cli_args import CAN_RESUME_USAGE, HANDOFF_USAGE, RESUME_USAGE, _parse_json_flag
+from ..cli_args import CAN_RESUME_USAGE, HANDOFF_USAGE, RESUME_USAGE, _parse_json_flag, _pop_value_flag
 from ..cli_helpers import (
     API_SCHEMA_VERSION,
     _json_failure,
@@ -19,7 +20,7 @@ from ..cli_helpers import (
     _write_update_notice,
 )
 from ..cli_render import _dim, _info, _success, _warn
-from ..config import PROVIDER_CODEX
+from ..config import PROVIDER_CLAUDE, PROVIDER_CODEX
 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
@@ -29,16 +30,29 @@ from ..provider_runtime import (
     _ensure_session_authentication,
     _get_auth_home,
     _run_interactive_provider_command,
+    with_requested_conversation,
 )
 from ..run_command import PROMPT_STDIN, read_run_prompt
 from ..run_usage import estimate_cost
 
-LAUNCH_USAGE = "Usage: cdx <name> [--dir PATH] [--prompt TEXT|--prompt-file PATH] [--resume] [--json]"
+LAUNCH_USAGE = "Usage: cdx <name> [--dir PATH] [--prompt TEXT|--prompt-file PATH|--task TEXT [--end-state TEXT]] [--resume] [--json]"
+
+#: The first message of a session started with --task. The end state is what the
+#: user's go-ahead covers: a bare "show me first" made sessions stop after a commit
+#: and wait for a push they could have made.
+TASK_PROMPT = """Task: {task}
+
+{end_state}
+
+Before starting, read this repository's instructions (AGENTS.md, CLAUDE.md and what they reference) and use its skills where one fits; they override general habits."""
+END_STATE = """End state: {end_state}
+Reaching it is approved: take every step it needs, including the commits, pushes or pull requests it names, without asking again. Stop and ask only for a decision it does not cover."""
+NO_END_STATE = """No end state was given: stop and show the result before any commit, push or pull request."""
 
 
 def _parse_launch_args(args):
     """Return the per-launch directory, initial prompt source and ordinary launch flags."""
-    values = {"--dir": None, "--prompt": None, "--prompt-file": None}
+    values = {"--dir": None, "--prompt": None, "--prompt-file": None, "--task": None, "--end-state": None}
     cleaned = []
     index = 0
     while index < len(args):
@@ -59,6 +73,13 @@ def _parse_launch_args(args):
         values[flag] = value
     if values["--prompt"] is not None and values["--prompt-file"] is not None:
         raise CdxError("cdx <name>: --prompt and --prompt-file are mutually exclusive.")
+    if values["--end-state"] is not None and values["--task"] is None:
+        raise CdxError("cdx <name>: --end-state goes with --task.")
+    if values["--task"] is not None:
+        if values["--prompt"] is not None or values["--prompt-file"] is not None:
+            raise CdxError("cdx <name>: --task replaces --prompt and --prompt-file.")
+        end = END_STATE.format(end_state=values["--end-state"]) if values["--end-state"] else NO_END_STATE
+        values["--prompt"] = TASK_PROMPT.format(task=values["--task"], end_state=end)
     if values["--prompt-file"] == PROMPT_STDIN:
         raise CdxError("cdx <name>: --prompt-file - is not supported; the interactive session needs standard input.")
     prompt = {"prompt": values["--prompt"], "prompt_file": values["--prompt-file"]}
@@ -140,12 +161,14 @@ def _format_resume_capability(capability, use_color=False):
     )
 
 def handle_can_resume(rest, ctx):
+    conversation_id, rest = _pop_value_flag(rest, "--conversation", CAN_RESUME_USAGE)
     json_flag, args = _parse_json_flag(rest)
     if len(args) != 1:
         raise CdxError(CAN_RESUME_USAGE)
     session = ctx["service"]["get_session"](args[0])
     if not session:
         raise CdxError(f"Unknown session: {args[0]}")
+    requested = with_requested_conversation(session, conversation_id) if conversation_id else session
     if session.get("enabled", True) is False:
         capability = {
             "session": session["name"],
@@ -155,8 +178,19 @@ def handle_can_resume(rest, ctx):
             "reason": "session_disabled",
             "command_preview": [],
         }
+    elif requested is None:
+        capability = {
+            "session": session["name"],
+            "provider": session["provider"],
+            "resumable": False,
+            "strategy": "provider_conversation_id",
+            "identity": conversation_id,
+            "provenance": "requested",
+            "reason": "conversation_not_found",
+            "command_preview": [],
+        }
     else:
-        capability = _resume_capability_for_session(session, ctx)
+        capability = _resume_capability_for_session(requested, ctx)
     if json_flag:
         _write_json(ctx, {
             "schema_version": API_SCHEMA_VERSION,
@@ -168,13 +202,15 @@ def handle_can_resume(rest, ctx):
     return 0
 
 def handle_resume(rest, ctx):
+    conversation_id, rest = _pop_value_flag(rest, "--conversation", RESUME_USAGE)
     directory, rest, prompt = _parse_launch_args(rest)
     if prompt["prompt"] is not None or prompt["prompt_file"] is not None:
         raise CdxError("cdx resume: --prompt and --prompt-file are not supported when resuming.")
     json_flag, args = _parse_json_flag(rest)
     if len(args) != 1:
         raise CdxError(RESUME_USAGE)
-    return handle_launch(args[0], ctx, resume=True, force_json=json_flag, directory=directory)
+    return handle_launch(args[0], ctx, resume=True, force_json=json_flag, directory=directory,
+                         conversation_id=conversation_id)
 
 
 def _notification_provisioning_enabled(session, ctx, json_flag):
@@ -202,7 +238,23 @@ def _notification_provisioning_enabled(session, ctx, json_flag):
     return True
 
 
-def handle_launch(command, ctx, initial_prompt=None, resume=False, force_json=None, directory=None):
+def _link_shared_memory(session, ctx, cwd, json_flag):
+    if session["provider"] != PROVIDER_CLAUDE or (session.get("launch") or {}).get("shared_memory") is not True:
+        return
+    try:
+        status, detail = shared_memory.link(_get_auth_home(session), ctx["service"]["base_dir"], cwd)
+    except OSError as error:
+        status, detail = "unsupported", str(error)
+    if json_flag or status == "linked":
+        return
+    if status == "conflict":
+        detail = f"merge these files by hand first: {', '.join(detail)}"
+    message = f"Shared memory not linked for {session['name']}"
+    ctx["out"](f"{_warn(message, ctx['use_color'])} {detail}\n")
+
+
+def handle_launch(command, ctx, initial_prompt=None, resume=False, force_json=None, directory=None,
+                  conversation_id=None):
     json_flag = "--json" in ctx.get("raw_args", ctx["options"].get("raw_args", []))
     if force_json is not None:
         json_flag = force_json
@@ -215,6 +267,8 @@ def handle_launch(command, ctx, initial_prompt=None, resume=False, force_json=No
         raise CdxError(f"Unknown session: {command}")
     if session.get("enabled", True) is False:
         raise CdxError(f"Session is disabled: {command}")
+    if conversation_id and with_requested_conversation(session, conversation_id) is None:
+        raise CdxError(f"Conversation {conversation_id} not found in session {command}.", code="conversation_not_found")
     capability = _resume_capability_for_session(session, ctx) if resume else None
     if capability and not capability["resumable"]:
         raise CdxError(
@@ -222,6 +276,8 @@ def handle_launch(command, ctx, initial_prompt=None, resume=False, force_json=No
         )
     cwd = _launch_directory(session, ctx, directory, json_flag)
     session = ctx["service"]["launch_session"](command, resume=resume)
+    if conversation_id:
+        session = with_requested_conversation(session, conversation_id)
     capability = _resume_capability_for_session(session, ctx) if resume else None
     if not json_flag and not ctx["stdin_is_tty"]:
         ctx["out"](f"Using directory: {cwd}\n")
@@ -262,6 +318,7 @@ def handle_launch(command, ctx, initial_prompt=None, resume=False, force_json=No
             # a real turn — so it gets no instruction it does not need.
             notice += " — approve them once in Codex to enable"
         ctx["out"](f"{_info(notice, ctx['use_color'])}\n")
+    _link_shared_memory(session, ctx, cwd, json_flag)
     runtime_run_id = None
 
     def runtime_lifecycle(event, info):
@@ -335,6 +392,8 @@ def handle_launch(command, ctx, initial_prompt=None, resume=False, force_json=No
     })
     if not json_flag:
         ctx["out"](f"{_goodbye_line(session, success_run_info, ctx['use_color'])}\n")
+    if retro.start(session, cwd, success_run_info.get("provider_transcript_path"), env=ctx.get("env")) and not json_flag:
+        ctx["out"](f"{_dim('Session retro started; read it later with `cdx retro`', ctx['use_color'])}\n")
     if json_flag:
         extra = {"session": ctx["service"]["get_session"](session["name"]), "cwd": cwd}
         if capability:

package/src/commands/maintenance.py

@@ -775,6 +775,7 @@ def handle_update(rest, ctx):
         package_root=ctx["options"].get("packageRoot"),
         prefix=ctx["options"].get("prefix"),
         base_prefix=ctx["options"].get("basePrefix"),
+        env=ctx.get("env"),
     )
     results = run_update_plan(plan, runner=ctx["options"].get("runUpdate"), env=ctx.get("env"))
     failed = any((result.get("returncode") != 0) for result in results)