cdx-manager 0.12.4 → 0.15.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "cdx-manager",
-  "version": "0.12.4",
+  "version": "0.15.0",
   "description": "Terminal session manager for Codex and Claude accounts.",
   "license": "MIT",
   "author": "Alexandre Agostini",
@@ -30,7 +30,7 @@
     "checksums",
     "changelogs",
     "src",
-    "!src/__pycache__",
+    "!src/**/__pycache__",
     "!src/**/*.pyc",
     "install.sh",
     "install.ps1",
@@ -46,7 +46,7 @@
     "test": "npm run test:py",
     "test:py": "node bin/python-runner.js -m pytest",
     "test:coverage": "node bin/python-runner.js -m pytest --cov=src --cov-report=term-missing",
-    "lint": "node --check bin/cdx.js && node --check bin/python-runner.js && node bin/python-runner.js scripts/verify_project_docs.py && node bin/python-runner.js -m ruff check . && node bin/python-runner.js -m py_compile bin/cdx src/*.py scripts/*.py test/test_*_py.py",
+    "lint": "node --check bin/cdx.js && node --check bin/python-runner.js && node bin/python-runner.js scripts/verify_project_docs.py && node bin/python-runner.js -m ruff check . && node bin/python-runner.js -m py_compile bin/cdx src/*.py src/commands/*.py scripts/*.py test/*.py",
     "release:validate": "node bin/python-runner.js scripts/verify_release_checksums.py",
     "prepublishOnly": "npm run release:validate && npm run lint && npm test",
     "link": "npm link",

package/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "cdx-manager"
-version = "0.12.4"
+version = "0.15.0"
 description = "Terminal session manager for Codex and Claude accounts."
 readme = "README.md"
 requires-python = ">=3.9"

package/src/cli.py

@@ -43,7 +43,9 @@ from .cli_commands import (
     handle_run,
     handle_run_report,
     handle_run_status,
+    handle_run_tail,
     handle_runs,
+    handle_schema,
     handle_select,
     handle_set,
     handle_stats,
@@ -78,7 +80,38 @@ from .status_view import (
 )
 from .update_check import check_for_update, check_logics_manager_for_update
 
-VERSION = "0.12.4"
+
+def _resolve_version():
+    """The version, resolved rather than restated.
+
+    This was a hardcoded string, a fourth copy alongside VERSION, package.json,
+    and pyproject.toml, with nothing keeping the four in step — so
+    `cdx --version` could report a release it was not.
+
+    The VERSION file next to the package wins when it exists, because that only
+    happens in a checkout, where it is the thing being edited and the installed
+    metadata is whatever was last `pip install`ed. Installed packages have no
+    such file and fall through to their own metadata.
+    """
+    version_file = os.path.join(
+        os.path.dirname(os.path.dirname(os.path.abspath(__file__))), "VERSION"
+    )
+    try:
+        with open(version_file, encoding="utf-8") as handle:
+            text = handle.read().strip()
+        if text:
+            return text
+    except OSError:
+        pass
+    try:
+        from importlib.metadata import version
+
+        return version("cdx-manager")
+    except Exception:  # noqa: BLE001 - any resolution failure falls back below
+        return "0.0.0"
+
+
+VERSION = _resolve_version()
 
 # Public surface: this module is a facade. Names below are imported above
 # purely to be re-exported (consumed by tests and external callers); listing
@@ -130,7 +163,9 @@ _COMMAND_HANDLERS = {
     "run": handle_run,
     "run-report": handle_run_report,
     "run-status": handle_run_status,
+    "run-tail": handle_run_tail,
     "runs": handle_runs,
+    "schema": handle_schema,
     "select": handle_select,
     "set": handle_set,
     "stats": handle_stats,
@@ -183,10 +218,12 @@ def _print_help(use_color=False):
         f"  {_style('cdx next [--json] [--refresh]', '36', use_color)}",
         f"  {_style('cdx reset <name> [--yes] [--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) [--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] --json', '36', use_color)}",
-        f"  {_style('cdx runs [--limit N] --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 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)}",
+        f"  {_style('cdx run-tail <run_id> [--lines N] --json', '36', use_color)}",
+        f"  {_style('cdx schema --json', '36', use_color)}",
         f"  {_style('cdx context show|path|init|edit|clear|set|append [text...] [--json]', '36', use_color)}",
         f"  {_style('cdx memory [--global|--project NAME_OR_PATH] [show|view|path|init|edit|clear|set|append|list] [text...] [--json]', '36', use_color)}",
         f"  {_style('cdx disk [profiles] [--candidates] [--json]', '36', use_color)}",
@@ -216,7 +253,7 @@ def _print_help(use_color=False):
         f"  {_style('cdx clean profiles (--tmp|--old-logs DAYS) [--yes] [--json]', '36', use_color)}",
         f"  {_style('cdx export <file> [--include-auth] [--sessions a,b] [--passphrase-env VAR|--passphrase-stdin] [--force] [--json]', '36', use_color)}",
         f"  {_style('cdx import <file> [--sessions a,b] [--passphrase-env VAR|--passphrase-stdin] [--force|--merge] [--allow-authless-force] [--json]', '36', use_color)}",
-        f"  {_style('cdx doctor [--severity OK|WARN|FAIL[,OK|WARN|FAIL...]] [--json]', '36', use_color)}",
+        f"  {_style('cdx doctor [--severity OK|WARN|FAIL[,OK|WARN|FAIL...]] [--check-provider-flags] [--json]', '36', use_color)}",
         f"  {_style('cdx repair [--dry-run] [--force] [--json]', '36', use_color)}",
         f"  {_style('cdx view [--json]', '36', use_color)}",
         f"  {_style('cdx update [all] [--check] [--yes] [--json] [--version TAG]', '36', use_color)}",
@@ -239,6 +276,25 @@ def wants_json(argv):
 
 def format_json_error(error):
     message = str(error)
+    # An error that already knows its own code keeps it. Only errors that never
+    # declared one fall back to sniffing the message prefix below.
+    declared = getattr(error, "code", None)
+    if declared:
+        allowed = getattr(error, "allowed", None)
+        # Same field set as run_result_payload's error object, so a caller does
+        # not need two shapes depending on which command raised.
+        return json.dumps({
+            "schema_version": API_SCHEMA_VERSION,
+            "ok": False,
+            "error": {
+                "source": "cdx",
+                "code": declared,
+                "message": message,
+                "arguments": list(getattr(error, "arguments", ()) or []),
+                "allowed_values": list(allowed) if allowed else None,
+                "exit_code": error.exit_code,
+            },
+        }, indent=2)
     code = "cdx_error"
     if message.startswith("Usage:"):
         code = "invalid_usage"
@@ -506,7 +562,11 @@ def main(argv, options=None):
         "service": service,
         "signal_emitter": signal_emitter,
         "spawn": spawn,
+        "spawn_detached": options.get("spawn_detached"),
         "spawn_headless": options.get("spawn_headless"),
+        # Stream `--prompt-file -` reads from. Distinct from "stdin", which is
+        # the {"isTTY": ...} descriptor the interactive paths use.
+        "prompt_stdin": options.get("prompt_stdin"),
         "spawn_sync": spawn_sync,
         "stdin_is_tty": stdin_is_tty,
         "version": VERSION,

package/src/cli_args.py

@@ -7,12 +7,21 @@ imported back there and used by the handlers.
 
 from datetime import datetime, timedelta
 
-from .config import PROVIDER_CODEX, PROVIDERS
-from .errors import CdxError
+from .config import (
+    MAX_LAUNCH_BUDGET_USD,
+    PERMISSION_ALIASES,
+    PERMISSION_INPUT_VALUES,
+    PERMISSION_VALUES,
+    PROVIDER_CODEX,
+    PROVIDERS,
+    REASONING_EFFORT_VALUES,
+    normalize_permission,
+)
+from .errors import CdxArgumentError, CdxError
 from .provider_runtime import _normalize_reasoning_effort
 
 STATUS_USAGE = "Usage: cdx status [--json] [--refresh|--cached] [--timeout SECONDS] | cdx status --small|-s [--refresh|--cached] [--timeout SECONDS] | cdx status <name> [--json] [--refresh|--cached] [--timeout SECONDS]"
-DOCTOR_USAGE = "Usage: cdx doctor [--severity OK|WARN|FAIL[,OK|WARN|FAIL...]] [--json]"
+DOCTOR_USAGE = "Usage: cdx doctor [--severity OK|WARN|FAIL[,OK|WARN|FAIL...]] [--check-provider-flags] [--json]"
 DISK_USAGE = "Usage: cdx disk [profiles] [--candidates] [--json]"
 REPAIR_USAGE = "Usage: cdx repair [--dry-run] [--force] [--json]"
 UPDATE_USAGE = "Usage: cdx update [all] [--check] [--yes] [--json] [--version TAG]"
@@ -22,8 +31,8 @@ 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> [--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] [--priority 0..100] [--json]"
-UNSET_USAGE = "Usage: cdx unset <name>|--sessions all|a,b|--provider PROVIDER (--power|--reasoning-effort|--permission|--fast|--rtk|--logics|--model|--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] [--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]"
 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]"
@@ -34,17 +43,37 @@ 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 PATH (--prompt-file PATH|--prompt TEXT) [--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] --json"
+RUN_USAGE = "Usage: 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] [--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_PERMISSION_VALUES = ("review", "default", "auto", "full", "workspace-write", "read-only", "danger-full-access")
-RUNS_USAGE = "Usage: cdx runs [--limit N] --json"
+# 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.
+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"
 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"
+SCHEMA_USAGE = "Usage: cdx schema --json"
+
+RUN_TAIL_DEFAULT_LINES = 50
+RUN_TAIL_MAX_LINES = 2000
+
+# Argument-failure codes emitted in `error.code`. Specific enough that a caller
+# branches on the code alone, never on the human message.
+ARG_CODE_MISSING = "missing_required_argument"
+ARG_CODE_MUTUALLY_EXCLUSIVE = "mutually_exclusive_arguments"
+ARG_CODE_INVALID_VALUE = "invalid_argument_value"
+ARG_CODE_OUT_OF_RANGE = "argument_value_out_of_range"
+ARG_CODE_UNKNOWN = "unknown_argument"
 
 
 def _parse_json_flag(args):
@@ -54,7 +83,7 @@ def _parse_json_flag(args):
 
 
 def _parse_doctor_args(args):
-    parsed = {"json": False, "severity": None}
+    parsed = {"json": False, "severity": None, "check_provider_flags": False}
     index = 0
     while index < len(args):
         arg = args[index]
@@ -62,6 +91,10 @@ def _parse_doctor_args(args):
             parsed["json"] = True
             index += 1
             continue
+        if arg == "--check-provider-flags":
+            parsed["check_provider_flags"] = True
+            index += 1
+            continue
         if arg == "--severity":
             if parsed["severity"] is not None or index + 1 >= len(args):
                 raise CdxError(DOCTOR_USAGE)
@@ -197,6 +230,17 @@ def _parse_priority_value(value):
     return priority
 
 
+def _parse_budget_value(value):
+    try:
+        budget = float(value)
+    except (TypeError, ValueError) as error:
+        raise CdxError(SET_USAGE) from error
+    # NaN compares false against every bound, so reject it before the range check.
+    if budget != budget or budget <= 0 or budget > MAX_LAUNCH_BUDGET_USD:
+        raise CdxError(SET_USAGE)
+    return budget
+
+
 def _parse_set_args(args):
     parsed = _parse_flag_args(args, {
         "--power": {"key": "power", "type": "str", "default": None},
@@ -205,6 +249,9 @@ def _parse_set_args(args):
         "--rtk": {"key": "rtk", "type": "str", "default": None, "transform": _parse_fast_value},
         "--logics": {"key": "logics", "type": "str", "default": None, "transform": _parse_fast_value},
         "--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},
         "--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)},
@@ -222,7 +269,7 @@ def _parse_set_args(args):
         raise CdxError(SET_USAGE)
     settings = {
         key: parsed[key]
-        for key in ("power", "permission", "fast", "rtk", "logics", "model", "priority")
+        for key in ("power", "permission", "fast", "rtk", "logics", "model", "fallback_model", "budget", "extra_args", "priority")
         if parsed[key] is not None
     }
     if not settings:
@@ -245,6 +292,9 @@ def _parse_unset_args(args):
         "--rtk": {"key": "rtk", "type": "bool", "default": False},
         "--logics": {"key": "logics", "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},
         "--all": {"key": "all", "type": "bool", "default": False},
         "--sessions": {"key": "sessions", "type": "str", "default": None, "transform": _parse_set_unset_sessions},
@@ -261,9 +311,11 @@ def _parse_unset_args(args):
         raise CdxError(UNSET_USAGE)
     if not parsed["names"] and not parsed["sessions"] and not parsed["provider"]:
         raise CdxError(UNSET_USAGE)
-    keys = ["power", "reasoning_effort", "permission", "fast", "rtk", "logics", "model", "priority"] if parsed["all"] else [
-        key for key in ("power", "reasoning_effort", "permission", "fast", "rtk", "logics", "model", "priority") if parsed[key]
-    ]
+    _UNSET_KEYS = (
+        "power", "reasoning_effort", "permission", "fast", "rtk", "logics",
+        "model", "fallback_model", "budget", "extra_args", "priority",
+    )
+    keys = list(_UNSET_KEYS) if parsed["all"] else [key for key in _UNSET_KEYS if parsed[key]]
     if not keys:
         raise CdxError(UNSET_USAGE)
     return {
@@ -338,7 +390,11 @@ def _parse_run_timeout_seconds(value):
     try:
         return _parse_timeout_seconds(value, RUN_USAGE)
     except CdxError as error:
-        raise CdxError(f"cdx run: --timeout-seconds must be a positive number; got {value!r}.") from error
+        raise CdxArgumentError(
+            f"cdx run: --timeout-seconds must be a positive number; got {value!r}.",
+            code=ARG_CODE_OUT_OF_RANGE,
+            arguments=["--timeout-seconds"],
+        ) from error
 
 
 def _parse_run_provider(value):
@@ -346,27 +402,183 @@ def _parse_run_provider(value):
         return _parse_provider_filter(value, RUN_USAGE)
     except CdxError as error:
         allowed = "|".join(PROVIDERS)
-        raise CdxError(f"cdx run: invalid --provider {value!r}; allowed values: {allowed}.") from error
+        raise CdxArgumentError(
+            f"cdx run: invalid --provider {value!r}; allowed values: {allowed}.",
+            code=ARG_CODE_INVALID_VALUE,
+            arguments=["--provider"],
+            allowed=PROVIDERS,
+        ) from error
 
 
 def _normalize_run_permission(value):
     if value is None:
         return None
-    text = str(value).strip().lower()
-    aliases = {
-        "workspace-write": "default",
-        "read-only": "review",
-        "danger-full-access": "full",
-    }
-    text = aliases.get(text, text)
-    if text not in ("review", "default", "auto", "full"):
+    text = normalize_permission(value)
+    if text is None:
         allowed = "|".join(RUN_PERMISSION_VALUES)
-        raise CdxError(f"cdx run: invalid --permission {value!r}; allowed values: {allowed}.")
+        raise CdxArgumentError(
+            f"cdx run: invalid --permission {value!r}; allowed values: {allowed}.",
+            code=ARG_CODE_INVALID_VALUE,
+            arguments=["--permission"],
+            allowed=RUN_PERMISSION_VALUES,
+        )
     return text
 
 
-def _parse_run_args(args):
+def cdx_schema():
+    """The machine-readable contract for programmatic callers.
+
+    Every value here is the same object the parser validates against, not a
+    parallel copy — `cdx schema --json` cannot advertise a value `cdx run`
+    rejects, which is exactly how the ollama `--experimental-yolo` mapping
+    survived unexercised (GitHub issue #8).
+    """
+    # No `schema_version` here: the JSON envelope already carries it, and two
+    # keys of that name in one payload would be one too many.
+    return {
+        "enums": {
+            "permission": {
+                "accepted": list(RUN_PERMISSION_VALUES),
+                "canonical": list(RUN_PERMISSION_CANONICAL_VALUES),
+                "aliases": dict(RUN_PERMISSION_ALIASES),
+            },
+            "reasoning_effort": {"accepted": list(RUN_EFFORT_VALUES)},
+            "power": {"accepted": list(RUN_EFFORT_VALUES)},
+            "kind": {"accepted": list(RUN_KIND_VALUES)},
+            "provider": {"accepted": list(PROVIDERS)},
+        },
+        # Passthrough arguments are deliberately absent from this contract.
+        # `cdx set --extra-args` reaches the provider unchanged and cdx never
+        # validates it, so publishing it here would claim a guarantee that does
+        # not exist. A caller must treat it as opaque.
+        "unvalidated": {
+            "extra_args": {
+                "reason": "Passed to the provider CLI unchanged; cdx neither parses nor verifies these arguments.",
+                "not_checked_by": ["cdx schema", "cdx doctor --check-provider-flags"],
+            },
+        },
+        "mutually_exclusive": [
+            {
+                "command": "run",
+                "arguments": ["session", "--provider"],
+                "reason": "A session already fixes its provider; pass one or the other.",
+            },
+            {
+                "command": "run",
+                "arguments": ["--prompt-file", "--prompt"],
+                "reason": "Exactly one prompt source.",
+            },
+            {
+                "command": "run",
+                "arguments": ["--detach", "--failover"],
+                "reason": "Failover has to watch the run to react to a rate limit; --detach stops watching.",
+            },
+        ],
+        # Not mutually exclusive: both may be given, and cdx accepts them when
+        # they agree. A caller generating validation from `mutually_exclusive`
+        # would otherwise reject a command line cdx would have run.
+        "must_match": [
+            {
+                "command": "run",
+                "arguments": ["--reasoning-effort", "--power"],
+                "reason": "Aliases of one setting; supplying both with different values fails.",
+            },
+        ],
+        # Every code a run-family command can put in `error.code`, not just the
+        # argument ones — a caller matching exhaustively over this list must not
+        # fall through on a code it will certainly see.
+        "error_codes": {
+            "arguments": [
+                ARG_CODE_MISSING,
+                ARG_CODE_MUTUALLY_EXCLUSIVE,
+                ARG_CODE_INVALID_VALUE,
+                ARG_CODE_OUT_OF_RANGE,
+                ARG_CODE_UNKNOWN,
+                "invalid_reasoning_effort",
+            ],
+            "run": [
+                "invalid_cwd",
+                "session_disabled",
+                "no_suitable_session",
+                "provider_cli_not_found",
+                "provider_start_failed",
+                "provider_failed",
+                "provider_timeout",
+                "cdx_error",
+            ],
+            "run_lookup": [
+                "run_not_found",
+                "run_output_unavailable",
+                "run_output_unreadable",
+            ],
+        },
+        "warning_codes": [
+            "network_disabled_by_permission",
+            "session_selected_without_status",
+            "limit_ignored_with_since",
+        ],
+    }
+
+
+def _parse_schema_args(args):
     parsed = _parse_flag_args(args, {
+        "--json": {"key": "json", "type": "bool", "default": False},
+    }, SCHEMA_USAGE)
+    if not parsed["json"]:
+        raise CdxError(SCHEMA_USAGE)
+    return parsed
+
+
+def _parse_run_flag_args(args, schema, usage, positionals_key=None, max_positionals=0):
+    """`_parse_flag_args` is shared by every command and raises a bare usage
+    error for an unrecognized flag or a value-less option. Only `run` promises a
+    specific code for those, so translate here rather than teaching the shared
+    parser about codes it does not need. Transforms that already raised a
+    `CdxArgumentError` keep their own, more precise code."""
+    try:
+        return _parse_flag_args(args, schema, usage, positionals_key, max_positionals)
+    except CdxArgumentError:
+        raise
+    except CdxError as error:
+        raise CdxArgumentError(str(error), code=ARG_CODE_UNKNOWN) from error
+
+
+def _parse_run_effort(reasoning_effort, power):
+    try:
+        return _normalize_reasoning_effort(
+            reasoning_effort=reasoning_effort,
+            power=power,
+            usage=RUN_USAGE,
+        )
+    except CdxError as error:
+        message = str(error)
+        if "must match" in message:
+            raise CdxArgumentError(
+                message,
+                code=ARG_CODE_MUTUALLY_EXCLUSIVE,
+                arguments=["--reasoning-effort", "--power"],
+            ) from error
+        # An empty value raises the bare usage line, which names neither flag.
+        # Blame the one actually supplied rather than guessing, since naming the
+        # offending argument is the entire point of this error.
+        if message.startswith("Unsupported power:") or (power is not None and reasoning_effort is None):
+            argument = "--power"
+        else:
+            argument = "--reasoning-effort"
+        # Keeps the pre-existing `invalid_reasoning_effort` code rather than
+        # flattening it into the generic invalid-value one: it was already
+        # specific, and callers may already branch on it. The new codes exist to
+        # split what used to be indistinguishable, not to rename what wasn't.
+        raise CdxArgumentError(
+            message,
+            code="invalid_reasoning_effort",
+            arguments=[argument],
+            allowed=RUN_EFFORT_VALUES,
+        ) from error
+
+
+def _parse_run_args(args):
+    parsed = _parse_run_flag_args(args, {
         "--cwd": {"key": "cwd", "type": "str", "default": None},
         "--prompt-file": {"key": "prompt_file", "type": "str", "default": None},
         "--prompt": {"key": "prompt", "type": "str", "default": None},
@@ -377,27 +589,51 @@ def _parse_run_args(args):
         "--power": {"key": "power", "type": "str", "default": None},
         "--permission": {"key": "permission", "type": "str", "default": None, "transform": _normalize_run_permission},
         "--timeout-seconds": {"key": "timeout_seconds", "type": "str", "default": None, "transform": _parse_run_timeout_seconds},
+        "--detach": {"key": "detach", "type": "bool", "default": False},
+        "--failover": {"key": "failover", "type": "bool", "default": False},
+        "--refresh": {"key": "refresh", "type": "bool", "default": False},
         "--json": {"key": "json", "type": "bool", "default": False},
     }, RUN_USAGE, positionals_key="names", max_positionals=1)
     if not parsed["json"]:
-        raise CdxError(RUN_JSON_REQUIRED)
+        raise CdxArgumentError(RUN_JSON_REQUIRED, code=ARG_CODE_MISSING, arguments=["--json"])
     name = parsed["names"][0] if parsed["names"] else None
     if name and parsed["provider"]:
-        raise CdxError(RUN_SESSION_PROVIDER_CONFLICT)
+        raise CdxArgumentError(
+            RUN_SESSION_PROVIDER_CONFLICT,
+            code=ARG_CODE_MUTUALLY_EXCLUSIVE,
+            arguments=["session", "--provider"],
+        )
     if not name and not parsed["provider"]:
-        raise CdxError(RUN_TARGET_REQUIRED)
+        raise CdxArgumentError(RUN_TARGET_REQUIRED, code=ARG_CODE_MISSING, arguments=["session", "--provider"])
     if not parsed["cwd"]:
-        raise CdxError(RUN_CWD_REQUIRED)
-    if bool(parsed["prompt_file"]) == bool(parsed["prompt"]):
-        raise CdxError(RUN_PROMPT_SOURCE_REQUIRED)
+        raise CdxArgumentError(RUN_CWD_REQUIRED, code=ARG_CODE_MISSING, arguments=["--cwd"])
+    if parsed["prompt_file"] and parsed["prompt"]:
+        raise CdxArgumentError(
+            RUN_PROMPT_SOURCE_REQUIRED,
+            code=ARG_CODE_MUTUALLY_EXCLUSIVE,
+            arguments=["--prompt-file", "--prompt"],
+        )
+    if parsed["detach"] and parsed["failover"]:
+        raise CdxArgumentError(
+            RUN_DETACH_FAILOVER_CONFLICT,
+            code=ARG_CODE_MUTUALLY_EXCLUSIVE,
+            arguments=["--detach", "--failover"],
+        )
+    if not parsed["prompt_file"] and not parsed["prompt"]:
+        raise CdxArgumentError(
+            RUN_PROMPT_SOURCE_REQUIRED,
+            code=ARG_CODE_MISSING,
+            arguments=["--prompt-file", "--prompt"],
+        )
     if parsed["kind"] not in RUN_KIND_VALUES:
         allowed = "|".join(RUN_KIND_VALUES)
-        raise CdxError(f"cdx run: invalid --kind {parsed['kind']!r}; allowed values: {allowed}.")
-    effort = _normalize_reasoning_effort(
-        reasoning_effort=parsed["reasoning_effort"],
-        power=parsed["power"],
-        usage=RUN_USAGE,
-    )
+        raise CdxArgumentError(
+            f"cdx run: invalid --kind {parsed['kind']!r}; allowed values: {allowed}.",
+            code=ARG_CODE_INVALID_VALUE,
+            arguments=["--kind"],
+            allowed=RUN_KIND_VALUES,
+        )
+    effort = _parse_run_effort(parsed["reasoning_effort"], parsed["power"])
     return {
         "name": name,
         "provider": parsed["provider"],
@@ -408,6 +644,9 @@ def _parse_run_args(args):
         "model": parsed["model"],
         "permission": parsed["permission"],
         "timeout_seconds": parsed["timeout_seconds"],
+        "detach": parsed["detach"],
+        "failover": parsed["failover"],
+        "refresh": parsed["refresh"],
         "reasoning_effort": effort.get("reasoning_effort"),
         "power": effort.get("power"),
     }
@@ -709,11 +948,28 @@ def _parse_import_args(args):
     return parsed
 
 
-def _parse_runs_args(rest):
-    return _parse_flag_args(rest, {
+def _parse_runs_args(rest, now=None):
+    now = now or datetime.now().astimezone()
+    parsed = _parse_flag_args(rest, {
         "--limit": {"key": "limit", "type": "str", "default": 20, "transform": _parse_positive_int},
+        "--since": {"key": "since", "type": "str", "default": None},
         "--json": {"key": "json", "type": "bool", "default": False},
     }, RUNS_USAGE, max_positionals=0)
+    since = None
+    if parsed["since"] is not None:
+        # Same cursor forms as `cdx history --since`, parsed by the same code:
+        # a caller that learned one syntax does not learn a second one.
+        since = _parse_since_value(parsed["since"], now, RUNS_USAGE)
+    return {
+        "limit": parsed["limit"],
+        "since": since,
+        # A cursor selects by completion time, not by row count. Keeping the
+        # caller's own --limit would silently reintroduce the miss it removes:
+        # 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),
+        "json": parsed["json"],
+    }
 
 
 def _parse_run_id_json_args(rest, usage):
@@ -723,3 +979,32 @@ def _parse_run_id_json_args(rest, usage):
     if not parsed["json"] or len(parsed["ids"]) != 1:
         raise CdxError(usage)
     return {"run_id": parsed["ids"][0], "json": True}
+
+
+def _parse_run_tail_args(rest):
+    parsed = _parse_flag_args(rest, {
+        "--lines": {"key": "lines", "type": "str", "default": RUN_TAIL_DEFAULT_LINES,
+                    "transform": _parse_run_tail_lines},
+        "--json": {"key": "json", "type": "bool", "default": False},
+    }, RUN_TAIL_USAGE, positionals_key="ids", max_positionals=1)
+    if not parsed["json"] or len(parsed["ids"]) != 1:
+        raise CdxError(RUN_TAIL_USAGE)
+    return {"run_id": parsed["ids"][0], "lines": parsed["lines"], "json": True}
+
+
+def _parse_run_tail_lines(value):
+    try:
+        parsed = int(value)
+    except (TypeError, ValueError) as error:
+        raise CdxArgumentError(
+            f"cdx run-tail: --lines must be an integer; got {value!r}.",
+            code=ARG_CODE_INVALID_VALUE,
+            arguments=["--lines"],
+        ) from error
+    if not 1 <= parsed <= RUN_TAIL_MAX_LINES:
+        raise CdxArgumentError(
+            f"cdx run-tail: --lines must be between 1 and {RUN_TAIL_MAX_LINES}; got {parsed}.",
+            code=ARG_CODE_OUT_OF_RANGE,
+            arguments=["--lines"],
+        )
+    return parsed