cdx-manager 0.21.5 → 0.22.0

package/src/cli.py

@@ -6,6 +6,7 @@ import sys
 from datetime import datetime, timezone
 
 from .agent_notify import handle_notify
+from .cli_args import SET_USAGE
 from .cli_commands import (
     API_SCHEMA_VERSION,
     STATUS_USAGE,
@@ -70,8 +71,10 @@ from .cli_render import (
     _visible_len,
     format_error,
 )
+from .commands.rescue import handle_rescue
 from .config import PROVIDER_OLLAMA
 from .errors import CdxError
+from .retro import handle_retro
 from .session_service import create_session_service
 from .status_view import (
     _format_blocking_quota,
@@ -174,6 +177,8 @@ _COMMAND_HANDLERS = {
     "rename": handle_rename,
     "resume": handle_resume,
     "can-resume": handle_can_resume,
+    "rescue": handle_rescue,
+    "retro": handle_retro,
     "rmv": handle_remove,
     "run": handle_run,
     "run-report": handle_run_report,
@@ -235,7 +240,7 @@ def _print_help(use_color=False):
         f"  {_style('cdx reset <name> [--yes] [--json]', '36', use_color)}",
         f"  {_style('cdx auth refresh <name|all> [--json]', '36', use_color)}",
         f"  {_style('cdx select --provider PROVIDER [--min-reasoning-effort minimal|low|medium|high|xhigh] [--min-power minimal|low|medium|high|xhigh] [--require-ready] [--refresh] --json', '36', use_color)}",
-        f"  {_style('cdx run [session] --cwd 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] [--refresh] --json', '36', use_color)}",
+        f"  {_style('cdx run [session] --cwd 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', '36', use_color)}",
         f"  {_style('cdx runs [--limit N] [--since 7d|today|DATE] --json', '36', use_color)}",
         f"  {_style('cdx run-status <run_id> --json', '36', use_color)}",
         f"  {_style('cdx run-report <run_id> --json', '36', use_color)}",
@@ -247,13 +252,15 @@ def _print_help(use_color=False):
         f"  {_style('cdx config <name> [--json]', '36', use_color)}",
         f"  {_style('cdx configs [--json]', '36', use_color)}",
         f"  {_style('cdx power|perm|fast|model <name|all|provider:PROVIDER|a,b> <value|default> [--json]', '36', use_color)}",
-        f"  {_style('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] [--model MODEL] [--priority 0..100] [--json]', '36', use_color)}",
+        f"  {_style(SET_USAGE[len('Usage: '):], '36', use_color)}",
         f"  {_style('cdx unset <name>|--sessions all|a,b|--provider PROVIDER (--power|--permission|--fast|--rtk|--logics|--notify|--notify-preview|--model|--priority|--all) [--json]', '36', use_color)}",
         f"  {_style('cdx history [name] [--limit N] [--summary] [--since 7d|today|DATE] [--from DATE] [--to DATE] [--json]', '36', use_color)}",
-        f"  {_style('cdx stats [name] [--since 7d|today|DATE] [--from DATE] [--to DATE] [--json]', '36', use_color)}",
+        f"  {_style('cdx stats [name] [--since 7d|today|DATE] [--from DATE] [--to DATE] [--by session|project|model] [--json]', '36', use_color)}",
         f"  {_style('cdx last [--json]', '36', use_color)}",
         f"  {_style('cdx resume <name> [--json]', '36', use_color)}",
         f"  {_style('cdx can-resume <name> [--json]', '36', use_color)}",
+        f"  {_style('cdx rescue [<session>] [--to <target>] [--yes] [--dry-run] [--json]', '36', use_color)}",
+        f"  {_style('cdx retro [--limit N] [--json]', '36', use_color)}",
         f"  {_style('cdx handoff <name> [--json]', '36', use_color)}",
         f"  {_style('cdx handoff <source> <target> [--source-conversation ID | --source-native-transcript PATH | --source-transcript PATH] [--json]', '36', use_color)}",
         f"  {_style('cdx add [provider] <name> [--model MODEL] [--json]', '36', use_color)}",
@@ -284,6 +291,7 @@ def _print_help(use_color=False):
         f"  {_style('cdx ready', '36', use_color)}  # next session to become ready",
         f"  {_style('cdx <name> [--json]', '36', use_color)}",
         f"  {_style('cdx <name> --prompt TEXT|--prompt-file PATH', '36', use_color)}  # start with a first message",
+        f"  {_style('cdx <name> --dir PATH --task TEXT --end-state TEXT', '36', use_color)}  # start on a task, with what the go-ahead covers",
         f"  {_style('cdx --help', '36', use_color)}",
         f"  {_style('cdx --version', '36', use_color)}",
     ])
@@ -533,7 +541,6 @@ def main(argv, options=None):
     stderr = options.get("stderr", sys.stderr)
     stdin_is_tty = options.get("stdin", {}).get("isTTY", hasattr(sys.stdin, "isatty") and sys.stdin.isatty())
     use_color = _should_use_color(env, stdout)
-    service = options.get("service") or create_session_service({"env": env})
     spawn = options.get("spawn")
     spawn_sync = options.get("spawn_sync")
     refresh_fn = options.get("refreshClaudeSessionStatus")
@@ -559,6 +566,10 @@ def main(argv, options=None):
         out(f"{_print_version()}\n")
         return 0
 
+    # Built after --help/--version: those must answer even where the home
+    # directory cannot be resolved (a service or task with a minimal environment).
+    service = options.get("service") or create_session_service({"env": env})
+
     if argv == ["--json"]:
         rows = service["format_list_rows"]()
         notices = _get_update_notices(service, env, options)

package/src/cli_args.py

@@ -16,6 +16,7 @@ from .config import (
     PROVIDERS,
     REASONING_EFFORT_VALUES,
     normalize_permission,
+    parse_on_off,
 )
 from .errors import CdxArgumentError, CdxError
 from .provider_runtime import _normalize_reasoning_effort
@@ -32,26 +33,27 @@ 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] [--model MODEL] [--fallback-model MODEL[,MODEL...]] [--budget USD] [--extra-args 'ARGS'] [--priority 0..100] [--json]"
-UNSET_USAGE = "Usage: cdx unset <name>|--sessions all|a,b|--provider PROVIDER (--power|--reasoning-effort|--permission|--fast|--rtk|--logics|--model|--fallback-model|--budget|--extra-args|--priority|--all) [--json]"
+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]"
 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.
@@ -213,13 +215,12 @@ def _parse_toggle_args(args, usage):
     return {"name": parsed["names"][0], "json": parsed["json"]}
 
 
-def _parse_fast_value(value):
-    text = str(value).strip().lower()
-    if text in ("on", "true", "1", "yes"):
-        return True
-    if text in ("off", "false", "0", "no"):
-        return False
-    raise CdxError(SET_USAGE)
+def _parse_fast_value(value, label="fast"):
+    return parse_on_off(value, label)
+
+
+def _on_off(label):
+    return lambda value: parse_on_off(value, label)
 
 
 def _parse_priority_value(value):
@@ -248,15 +249,19 @@ def _parse_set_args(args):
         "--power": {"key": "power", "type": "str", "default": None},
         "--permission": {"key": "permission", "type": "str", "default": None},
         "--fast": {"key": "fast", "type": "str", "default": None, "transform": _parse_fast_value},
-        "--rtk": {"key": "rtk", "type": "str", "default": None, "transform": _parse_fast_value},
-        "--logics": {"key": "logics", "type": "str", "default": None, "transform": _parse_fast_value},
-        "--notify": {"key": "notify", "type": "str", "default": None, "transform": _parse_fast_value},
-        "--notify-preview": {"key": "notify_preview", "type": "str", "default": None, "transform": _parse_fast_value},
+        "--rtk": {"key": "rtk", "type": "str", "default": None, "transform": _on_off("rtk")},
+        "--logics": {"key": "logics", "type": "str", "default": None, "transform": _on_off("logics")},
+        "--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},
@@ -273,7 +278,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", "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:
@@ -297,11 +302,15 @@ def _parse_unset_args(args):
         "--logics": {"key": "logics", "type": "bool", "default": False},
         "--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)},
@@ -318,8 +327,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",
-        "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:
@@ -510,8 +519,17 @@ def cdx_schema():
                 "provider_start_failed",
                 "provider_failed",
                 "provider_timeout",
+                "run_cancelled",
+                "too_many_runs",
+                "failover_exhausted",
+                "failover_limit_reached",
+                "invalid_request",
                 "cdx_error",
             ],
+            # The error code on a run record the stale sweep closed.
+            "run_record": [
+                "stale_process",
+            ],
             "run_lookup": [
                 "run_not_found",
                 "run_output_unavailable",
@@ -522,6 +540,26 @@ def cdx_schema():
             "network_disabled_by_permission",
             "session_selected_without_status",
             "limit_ignored_with_since",
+            "claude_auth_probe_failed",
+            "claude_refresh_failed",
+            "disk_cleanup_available",
+            "update_available",
+            "logics_manager_update_available",
+            "update_version_check_failed",
+            "update_version_mismatch",
+            "logics_manager_missing",
+            "logics_viewer_failed",
+            "logics_viewer_root_invalid",
+            "tray_autostart_unsupported",
+            "tray_companion_missing",
+            "tray_companion_not_aligned",
+            "tray_companion_not_available",
+            "tray_companion_not_installed",
+            "tray_companion_restart_pending",
+            "tray_companion_updated",
+            "tray_plugin_action_unknown",
+            "tray_plugin_unknown",
+            "tray_terminal_invalid",
         ],
     }
 
@@ -583,6 +621,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},
@@ -599,6 +648,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"]:
@@ -653,6 +704,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"),
@@ -817,12 +870,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"],
     }
 

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(
@@ -303,11 +313,15 @@ def _format_launch_config(session, use_color=False):
         ("logics", "Logics"),
         ("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),
@@ -329,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"):
+    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"):
+        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/codex_usage.py

@@ -247,7 +247,7 @@ def _request_codex_app_server(auth_home, method, params, failure_reason, timeout
             stdout=subprocess.PIPE,
             stderr=subprocess.DEVNULL,
             env=env,
-            text=True,
+            text=True, encoding="utf-8", errors="replace",
             bufsize=1,
         )
         thread = threading.Thread(target=_reader_thread, args=(process.stdout, output), daemon=True)

package/src/commands/launch.py

@@ -6,6 +6,7 @@ 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_helpers import (
@@ -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
@@ -33,12 +34,24 @@ from ..provider_runtime import (
 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 +72,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"]}
@@ -202,6 +222,21 @@ def _notification_provisioning_enabled(session, ctx, json_flag):
     return True
 
 
+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):
     json_flag = "--json" in ctx.get("raw_args", ctx["options"].get("raw_args", []))
     if force_json is not None:
@@ -262,6 +297,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 +371,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)