cdx-manager 0.6.5 → 0.7.0

package/README.md

@@ -1,6 +1,6 @@
 # CDX Manager
 
-[![License](https://img.shields.io/badge/license-MIT-4C8BF5)](LICENSE) ![Version](https://img.shields.io/badge/version-v0.6.5-4C8BF5) ![Python](https://img.shields.io/badge/python-3.9%2B-3776AB?logo=python&logoColor=white)
+[![License](https://img.shields.io/badge/license-MIT-4C8BF5)](LICENSE) ![Version](https://img.shields.io/badge/version-v0.7.0-4C8BF5) ![Python](https://img.shields.io/badge/python-3.9%2B-3776AB?logo=python&logoColor=white)
 
 **Run multiple Codex, Claude, Antigravity, and Ollama sessions from one terminal. Switch between accounts instantly.**
 
@@ -134,7 +134,7 @@ For a specific version:
 
 ```bash
 curl -fsSL https://raw.githubusercontent.com/AlexAgo83/cdx-manager/main/install.sh -o install.sh
-CDX_VERSION=v0.6.5 sh install.sh
+CDX_VERSION=v0.7.0 sh install.sh
 ```
 
 From source:
@@ -263,6 +263,7 @@ cdx set work --power medium --permission full --fast off
 cdx set personal --power low --permission review
 cdx set --sessions all --permission auto
 cdx set --provider ollama --model llama3.2
+cdx set work --priority 80
 cdx power all low
 cdx perm provider:claude review
 cdx model provider:ollama llama3.2
@@ -275,12 +276,13 @@ Those values are stored on the session and reapplied every time you run `cdx wor
 cdx unset work --power
 cdx unset --sessions work,personal --fast
 cdx unset --provider claude --permission
+cdx unset work --priority
 cdx unset work --all
 cdx power all default
 cdx model provider:ollama default
 ```
 
-`--power` maps to Codex `model_reasoning_effort` and Claude `--effort`. `--permission` maps to provider-native permission flags. `--fast on` uses low effort when no explicit power is set.
+`--power` maps to Codex `model_reasoning_effort` and Claude `--effort`. `--permission` maps to provider-native permission flags. `--fast on` uses low effort when no explicit power is set. `--priority` is a 0..100 selector preference used as a tie-breaker after readiness and availability.
 
 ### Launch History
 
@@ -317,8 +319,8 @@ cdx history --summary --from 2026-05-01 --to 2026-05-28
 | `cdx enable <name> [--json]` | Re-enable a disabled session |
 | `cdx config <name> [--json]` | Show persistent launch settings for a session |
 | `cdx power\|perm\|fast\|model <name\|all\|provider:PROVIDER\|a,b> <value\|default> [--json]` | Shortcut commands for setting or clearing one launch setting |
-| `cdx set <name>\|--sessions all\|a,b\|--provider PROVIDER [--power low\|medium\|high\|xhigh\|max] [--permission review\|default\|auto\|full] [--fast on\|off] [--model MODEL] [--json]` | Persist launch settings for one or more sessions |
-| `cdx unset <name>\|--sessions all\|a,b\|--provider PROVIDER (--power\|--permission\|--fast\|--model\|--all) [--json]` | Remove persisted launch settings and fall back to provider defaults |
+| `cdx set <name>\|--sessions all\|a,b\|--provider PROVIDER [--power low\|medium\|high\|xhigh\|max] [--permission review\|default\|auto\|full] [--fast on\|off] [--model MODEL] [--priority 0..100] [--json]` | Persist launch settings for one or more sessions |
+| `cdx unset <name>\|--sessions all\|a,b\|--provider PROVIDER (--power\|--permission\|--fast\|--model\|--priority\|--all) [--json]` | Remove persisted launch settings and fall back to provider defaults |
 | `cdx history [name] [--limit N] [--summary] [--since 7d\|today\|DATE] [--from DATE] [--to DATE] [--json]` | Show recent launch history or aggregate total launch time per assistant, optionally filtered by period |
 | `cdx last [--json]` | Launch the most recent existing session from launch history |
 | `cdx context show\|path\|init\|edit\|clear\|set [text...] [--json]` | Manage the shared Markdown context for the current workspace |
@@ -334,6 +336,8 @@ cdx history --summary --from 2026-05-01 --to 2026-05-28
 | `cdx ready [--refresh] [--json]` | Schedule an OS notification for the next cooling-down assistant that becomes ready, then return immediately |
 | `cdx notify <name> --at-reset [--poll seconds] [--once] [--schedule] [--refresh] [--json]` | Wait for a session reset time or schedule an OS wake-up notification when due |
 | `cdx notify --next-ready [--poll seconds] [--once] [--schedule] [--refresh] [--json]` | Wait until the recommended session is usable, or schedule the next known reset notification |
+| `cdx select --provider PROVIDER [--min-reasoning-effort low\|medium\|high] [--min-power low\|medium\|high] [--require-ready] [--refresh] --json` | Select a suitable session for headless automation |
+| `cdx run [session] --cwd PATH (--prompt-file PATH\|--prompt TEXT) [--provider PROVIDER] [--model MODEL] [--reasoning-effort low\|medium\|high] [--power low\|medium\|high] [--permission MODE] [--timeout-seconds N] --json` | Run one headless task and return a stable JSON result |
 | `cdx status [--json] [--refresh]` | Show token usage table for all sessions; JSON returns a versioned payload with structured warnings |
 | `cdx status --small [--refresh]` / `cdx status -s [--refresh]` | Show compact token usage table without provider, blocking quota, credits, and updated columns |
 | `cdx status <name> [--json] [--refresh]` | Show detailed usage breakdown for one session |
@@ -371,6 +375,8 @@ Commands with machine-readable output:
 - `cdx update --json`
 - `cdx ready --json`
 - `cdx notify ... --json`
+- `cdx select ... --json`
+- `cdx run ... --json`
 
 Success payloads follow a shared envelope:
 
@@ -387,7 +393,7 @@ Success payloads follow a shared envelope:
 }
 ```
 
-Errors use a shared stderr JSON envelope whenever `--json` is present:
+Most commands use a shared stderr JSON envelope for errors whenever `--json` is present:
 
 ```json
 {
@@ -401,10 +407,44 @@ Errors use a shared stderr JSON envelope whenever `--json` is present:
 }
 ```
 
-`status --json` and similar commands also use the same envelope and place non-fatal issues in `warnings` instead of mixing plain-text diagnostics into `stderr`.
+`status --json` and similar commands also use the same envelope and place non-fatal issues in `warnings` instead of mixing plain-text diagnostics into `stderr`. `cdx run --json` is the exception: it always writes one final JSON payload to stdout, including cdx-side and provider-start errors, so supervisors can parse a single result stream while provider stdout and stderr are captured to files.
 
 This makes `cdx-manager` usable from editor plugins, scripts, and desktop apps without scraping human-readable terminal output.
 
+### Headless Runs
+
+`cdx run` is designed for supervisors such as Orchestia. In `--json` mode, stdout contains only the final JSON payload; provider stdout and stderr are captured to files.
+
+```bash
+cdx run codex-work \
+  --cwd /path/to/workspace \
+  --prompt-file task_prompt.md \
+  --model gpt-5.3-codex \
+  --reasoning-effort low \
+  --permission workspace-write \
+  --timeout-seconds 1800 \
+  --json
+```
+
+Use provider-based auto-selection when the caller wants cdx-manager to pick the account:
+
+```bash
+cdx run \
+  --provider codex \
+  --cwd /path/to/workspace \
+  --prompt "Summarize the repo status." \
+  --reasoning-effort low \
+  --json
+```
+
+The result includes `run_id`, selected `session`, `provider`, `exit_code`, `duration_seconds`, absolute `transcript_path`, `stdout_path`, `stderr_path`, and normalized usage token fields. Token counts are `null` when the provider does not expose them.
+
+`cdx select` exposes the same session selection logic directly:
+
+```bash
+cdx select --provider codex --min-reasoning-effort low --require-ready --json
+```
+
 ---
 
 ## Backup And Restore

package/changelogs/CHANGELOGS_0_7_0.md

@@ -0,0 +1,49 @@
+# Changelog (`0.6.5 -> 0.7.0`)
+
+Release date: 2026-05-29
+
+## Headless Automation
+
+- Added `cdx run --json` as a headless execution contract for automation clients such as Orchestia.
+- Added explicit session execution, provider-based auto-selection, inline prompt and prompt-file support, working-directory validation, timeout handling, and stable run metadata.
+- Kept JSON mode stdout reserved for the final response so callers can parse command output without terminal UI noise.
+- Returned structured cdx-side and provider-side error envelopes for missing provider CLIs, invalid launch inputs, provider start failures, disabled sessions, and reasoning validation errors.
+
+## Session Selection
+
+- Added `cdx select --json` with deterministic ranking from provider match, readiness, cooldown, quota health, configured priority, reasoning capability, and session name.
+- Reused the same selector from `cdx run --provider ...`.
+- Added priority handling improvements, including configured-priority tie-breaking and clearing selection priority.
+- Allowed ready selection for local providers where remote quota signals are not applicable.
+
+## Reasoning Effort
+
+- Added provider-neutral `--reasoning-effort low|medium|high` handling.
+- Kept `--power` as a compatibility alias and rejected conflicting values with cdx-sourced JSON errors.
+- Mapped normalized effort into Codex launch options while leaving clear extension points for other providers.
+
+## Artifacts and Diagnostics
+
+- Added transcript, stdout, and stderr artifact reporting for headless runs.
+- Returned absolute artifact paths and normalized nullable token usage fields on success and failure responses.
+- Hardened artifact and timeout tests to cover provider failures and unknown usage.
+
+## Documentation and Release Readiness
+
+- Documented the Orchestia headless delivery, headless CLI options, selection reasons, and JSON error stream behavior.
+- Completed Logics release-gate documentation with rollback coverage, project changelog, release notes, duplicate triage, and release gate artifacts.
+- Carried forward the `v0.6.5` release checksum metadata so standalone installer integrity checks can resolve the previous release.
+
+## Release Metadata
+
+- Updated package metadata, CLI version output, README badge, pinned installer example, and release changelog to `v0.7.0`.
+
+## Validation and Regression Evidence
+
+- `python -m py_compile bin/cdx src/*.py test/test_*_py.py`
+- `python -m unittest discover -s test -p 'test_*_py.py'`
+- `npm run lint`
+- `npm test`
+- `npm pack --dry-run`
+- `python -m build`
+- `python -m twine check dist/*`

package/checksums/release-archives.json

@@ -24,6 +24,10 @@
     "v0.6.4": {
       "github_tarball_sha256": "f7c83dd1ae7506cf1ae6420e718a285f4dc96a10fb3a19e24cc17e79d75a46b4",
       "github_zip_sha256": "d602800cf6b54f1e0adea751cc6b686ab2fc4a224715ade94f761df2ff7da2af"
+    },
+    "v0.6.5": {
+      "github_tarball_sha256": "f2280917ea75b5ae1e99a99b011f09704d89b1a7ae42497f5093e6fff9f814d9",
+      "github_zip_sha256": "0b8491037310ed82cf44419d0de887bc0f768c6690c69153992fc4d5cda69676"
     }
   }
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "cdx-manager",
-  "version": "0.6.5",
+  "version": "0.7.0",
   "description": "Terminal session manager for Codex and Claude accounts.",
   "license": "MIT",
   "author": "Alexandre Agostini",

package/pyproject.toml

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

package/src/cli.py

@@ -28,6 +28,8 @@ from .cli_commands import (
     handle_remove,
     handle_repair,
     handle_rename,
+    handle_run,
+    handle_select,
     handle_status,
     handle_set,
     handle_unset,
@@ -55,7 +57,7 @@ from .status_view import (
 )
 from .update_check import check_for_update
 
-VERSION = "0.6.5"
+VERSION = "0.7.0"
 
 
 # ---------------------------------------------------------------------------
@@ -72,11 +74,13 @@ def _print_help(use_color=False):
         f"  {_style('cdx status [--json] [--refresh]', '36', use_color)}",
         f"  {_style('cdx status --small|-s [--refresh]', '36', use_color)}",
         f"  {_style('cdx status <name> [--json] [--refresh]', '36', use_color)}",
+        f"  {_style('cdx select --provider PROVIDER [--min-reasoning-effort low|medium|high] [--min-power low|medium|high] [--require-ready] [--refresh] --json', '36', use_color)}",
+        f"  {_style('cdx run [session] --cwd PATH (--prompt-file PATH|--prompt TEXT) [--provider PROVIDER] [--model MODEL] [--reasoning-effort low|medium|high] [--power low|medium|high] [--permission review|default|auto|full|workspace-write|read-only|danger-full-access] [--timeout-seconds N] --json', '36', use_color)}",
         f"  {_style('cdx context show|path|init|edit|clear|set [text...] [--json]', '36', use_color)}",
         f"  {_style('cdx config <name> [--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 low|medium|high|xhigh|max] [--permission review|default|auto|full] [--fast on|off] [--model MODEL] [--json]', '36', use_color)}",
-        f"  {_style('cdx unset <name>|--sessions all|a,b|--provider PROVIDER (--power|--permission|--fast|--model|--all) [--json]', '36', use_color)}",
+        f"  {_style('cdx set <name>|--sessions all|a,b|--provider PROVIDER [--power low|medium|high|xhigh|max] [--permission review|default|auto|full] [--fast on|off] [--model MODEL] [--priority 0..100] [--json]', '36', use_color)}",
+        f"  {_style('cdx unset <name>|--sessions all|a,b|--provider PROVIDER (--power|--permission|--fast|--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 last [--json]', '36', use_color)}",
         f"  {_style('cdx handoff <name> [--json]', '36', use_color)}",
@@ -228,12 +232,13 @@ def main(argv, options=None):
         "service": service,
         "signal_emitter": signal_emitter,
         "spawn": spawn,
+        "spawn_headless": options.get("spawn_headless"),
         "spawn_sync": spawn_sync,
         "stdin_is_tty": stdin_is_tty,
         "version": VERSION,
         "cwd": options.get("cwd") or os.getcwd(),
         "update_notice": _get_update_notice(service, env, options) if command not in (
-            "add", "cp", "ren", "rename", "mv", "rmv", "clean", "doctor", "repair", "update", "ready", "notify", "context", "config", "set", "unset", "power", "perm", "fast", "model", "history", "handoff", "login", "logout", "disable", "enable", "export", "import", "help", "version"
+            "add", "cp", "ren", "rename", "mv", "rmv", "clean", "doctor", "repair", "update", "ready", "notify", "context", "config", "set", "unset", "power", "perm", "fast", "model", "history", "handoff", "login", "logout", "disable", "enable", "export", "import", "select", "run", "help", "version"
         ) else None,
         "use_color": use_color,
     }
@@ -309,6 +314,12 @@ def main(argv, options=None):
     if command == "status":
         return handle_status(rest, ctx)
 
+    if command == "select":
+        return handle_select(rest, ctx)
+
+    if command == "run":
+        return handle_run(rest, ctx)
+
     if command == "login":
         return handle_login(rest, ctx)
 

package/src/cli_commands.py

@@ -33,7 +33,9 @@ from .notify import (
 from .provider_runtime import (
     _ensure_session_authentication,
     _list_launch_transcript_paths,
+    _normalize_reasoning_effort,
     _probe_provider_auth,
+    _run_headless_provider_command,
     _run_interactive_provider_command,
 )
 from .repair import format_repair_report, repair_health
@@ -51,12 +53,14 @@ EXPORT_USAGE = "Usage: cdx export <file> [--include-auth] [--force] [--json] [--
 IMPORT_USAGE = "Usage: cdx import <file> [--force] [--json] [--sessions name1,name2] [--passphrase-env VAR]"
 CONTEXT_USAGE = "Usage: cdx context show|path|init|edit|clear|set [text...] [--json]"
 HANDOFF_USAGE = "Usage: cdx handoff <name> [--json] | cdx handoff <source> <target> [--json]"
-SET_USAGE = "Usage: cdx set <name>|--sessions all|a,b|--provider PROVIDER [--power low|medium|high|xhigh|max] [--permission review|default|auto|full] [--fast on|off] [--model MODEL] [--json]"
-UNSET_USAGE = "Usage: cdx unset <name>|--sessions all|a,b|--provider PROVIDER (--power|--permission|--fast|--model|--all) [--json]"
+SET_USAGE = "Usage: cdx set <name>|--sessions all|a,b|--provider PROVIDER [--power low|medium|high|xhigh|max] [--permission review|default|auto|full] [--fast on|off] [--model MODEL] [--priority 0..100] [--json]"
+UNSET_USAGE = "Usage: cdx unset <name>|--sessions all|a,b|--provider PROVIDER (--power|--permission|--fast|--model|--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]"
 HISTORY_USAGE = "Usage: cdx history [name] [--limit N] [--summary] [--since 7d|today|DATE] [--from DATE] [--to DATE] [--json]"
 LAST_USAGE = "Usage: cdx last [--json]"
+SELECT_USAGE = "Usage: cdx select --provider PROVIDER [--min-reasoning-effort low|medium|high] [--min-power low|medium|high] [--require-ready] [--refresh] --json"
+RUN_USAGE = "Usage: cdx run [session] --cwd PATH (--prompt-file PATH|--prompt TEXT) [--provider PROVIDER] [--model MODEL] [--reasoning-effort low|medium|high] [--power low|medium|high] [--permission review|default|auto|full|workspace-write|read-only|danger-full-access] [--timeout-seconds N] --json"
 API_SCHEMA_VERSION = 1
 HANDOFF_TRANSCRIPT_CHARS = 120000
 HANDOFF_NATIVE_TRANSCRIPT_CANDIDATES = 64
@@ -78,6 +82,23 @@ def _json_success(action, message, warnings=None, **extra):
     return payload
 
 
+def _json_failure(action, code, message, source="cdx", exit_code=1, warnings=None, **extra):
+    payload = {
+        "schema_version": API_SCHEMA_VERSION,
+        "ok": False,
+        "action": action,
+        "warnings": warnings or [],
+        "error": {
+            "source": source,
+            "code": code,
+            "message": message,
+            "exit_code": exit_code,
+        },
+    }
+    payload.update(extra)
+    return payload
+
+
 def _write_json(ctx, payload):
     ctx["out"](f"{json.dumps(payload, indent=2)}\n")
 
@@ -467,12 +488,23 @@ def _parse_fast_value(value):
     raise CdxError(SET_USAGE)
 
 
+def _parse_priority_value(value):
+    try:
+        priority = int(value)
+    except (TypeError, ValueError) as error:
+        raise CdxError(SET_USAGE) from error
+    if priority < 0 or priority > 100:
+        raise CdxError(SET_USAGE)
+    return priority
+
+
 def _parse_set_args(args):
     parsed = _parse_flag_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},
         "--model": {"key": "model", "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)},
         "--json": {"key": "json", "type": "bool", "default": False},
@@ -487,7 +519,7 @@ def _parse_set_args(args):
         raise CdxError(SET_USAGE)
     settings = {
         key: parsed[key]
-        for key in ("power", "permission", "fast", "model")
+        for key in ("power", "permission", "fast", "model", "priority")
         if parsed[key] is not None
     }
     if not settings:
@@ -507,6 +539,7 @@ def _parse_unset_args(args):
         "--permission": {"key": "permission", "type": "bool", "default": False},
         "--fast": {"key": "fast", "type": "bool", "default": False},
         "--model": {"key": "model", "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},
         "--provider": {"key": "provider", "type": "str", "default": None, "transform": lambda value: _parse_provider_filter(value, UNSET_USAGE)},
@@ -520,8 +553,8 @@ 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", "permission", "fast", "model"] if parsed["all"] else [
-        key for key in ("power", "permission", "fast", "model") if parsed[key]
+    keys = ["power", "permission", "fast", "model", "priority"] if parsed["all"] else [
+        key for key in ("power", "permission", "fast", "model", "priority") if parsed[key]
     ]
     if not keys:
         raise CdxError(UNSET_USAGE)
@@ -543,6 +576,99 @@ def _parse_config_args(args):
     return {"name": parsed["names"][0], "json": parsed["json"]}
 
 
+def _parse_select_args(args):
+    parsed = _parse_flag_args(args, {
+        "--provider": {"key": "provider", "type": "str", "default": None, "transform": lambda value: _parse_provider_filter(value, SELECT_USAGE)},
+        "--min-reasoning-effort": {"key": "min_reasoning_effort", "type": "str", "default": None},
+        "--min-power": {"key": "min_power", "type": "str", "default": None},
+        "--require-ready": {"key": "require_ready", "type": "bool", "default": False},
+        "--refresh": {"key": "refresh", "type": "bool", "default": False},
+        "--json": {"key": "json", "type": "bool", "default": False},
+    }, SELECT_USAGE)
+    if not parsed["provider"] or not parsed["json"]:
+        raise CdxError(SELECT_USAGE)
+    effort = _normalize_reasoning_effort(
+        reasoning_effort=parsed["min_reasoning_effort"],
+        power=parsed["min_power"],
+        usage=SELECT_USAGE,
+    ).get("reasoning_effort")
+    return {
+        "provider": parsed["provider"],
+        "min_reasoning_effort": effort,
+        "require_ready": parsed["require_ready"],
+        "refresh": parsed["refresh"],
+        "json": parsed["json"],
+    }
+
+
+def _parse_timeout_seconds(value):
+    try:
+        parsed = float(value)
+    except (TypeError, ValueError) as error:
+        raise CdxError(RUN_USAGE) from error
+    if parsed <= 0:
+        raise CdxError(RUN_USAGE)
+    return parsed
+
+
+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"):
+        raise CdxError(RUN_USAGE)
+    return text
+
+
+def _parse_run_args(args):
+    parsed = _parse_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},
+        "--provider": {"key": "provider", "type": "str", "default": None, "transform": lambda value: _parse_provider_filter(value, RUN_USAGE)},
+        "--model": {"key": "model", "type": "str", "default": None},
+        "--reasoning-effort": {"key": "reasoning_effort", "type": "str", "default": None},
+        "--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_timeout_seconds},
+        "--json": {"key": "json", "type": "bool", "default": False},
+    }, RUN_USAGE, positionals_key="names", max_positionals=1)
+    if not parsed["json"]:
+        raise CdxError(RUN_USAGE)
+    name = parsed["names"][0] if parsed["names"] else None
+    if name and parsed["provider"]:
+        raise CdxError(RUN_USAGE)
+    if not name and not parsed["provider"]:
+        raise CdxError(RUN_USAGE)
+    if not parsed["cwd"]:
+        raise CdxError(RUN_USAGE)
+    if bool(parsed["prompt_file"]) == bool(parsed["prompt"]):
+        raise CdxError(RUN_USAGE)
+    effort = _normalize_reasoning_effort(
+        reasoning_effort=parsed["reasoning_effort"],
+        power=parsed["power"],
+        usage=RUN_USAGE,
+    )
+    return {
+        "name": name,
+        "provider": parsed["provider"],
+        "cwd": parsed["cwd"],
+        "prompt_file": parsed["prompt_file"],
+        "prompt": parsed["prompt"],
+        "model": parsed["model"],
+        "permission": parsed["permission"],
+        "timeout_seconds": parsed["timeout_seconds"],
+        "reasoning_effort": effort.get("reasoning_effort"),
+        "power": effort.get("power"),
+    }
+
+
 def _parse_positive_int(value):
     try:
         parsed = int(value)
@@ -1025,6 +1151,223 @@ def handle_enable(rest, ctx):
     return 0
 
 
+def handle_select(rest, ctx):
+    parsed = _parse_select_args(rest)
+    selected = _select_headless_session(
+        ctx,
+        parsed["provider"],
+        min_reasoning_effort=parsed["min_reasoning_effort"],
+        require_ready=parsed["require_ready"],
+        force_refresh=parsed["refresh"],
+    )
+    policy = "ready_then_cooldown_then_health_then_priority_then_name"
+    if not selected:
+        message = "No suitable session found."
+        _write_json(ctx, _json_failure(
+            "select",
+            "no_suitable_session",
+            message,
+            provider=parsed["provider"],
+            min_reasoning_effort=parsed["min_reasoning_effort"],
+            require_ready=parsed["require_ready"],
+            selection_policy=policy,
+        ))
+        return 1
+    session = selected["session"]
+    row = selected.get("row") or {}
+    reason = "highest availability suitable session"
+    _write_json(ctx, _json_success(
+        "select",
+        f"Selected session {session['name']}",
+        session=session["name"],
+        provider=session["provider"],
+        reason=reason,
+        selection_policy=policy,
+        min_reasoning_effort=parsed["min_reasoning_effort"],
+        reasoning_effort=_session_reasoning_effort(session),
+        available_pct=row.get("available_pct"),
+        auth_status=row.get("auth_status"),
+    ))
+    return 0
+
+
+def _read_run_prompt(parsed):
+    if parsed.get("prompt") is not None:
+        return parsed["prompt"]
+    try:
+        with open(parsed["prompt_file"], "r", encoding="utf-8") as handle:
+            return handle.read()
+    except OSError as error:
+        raise CdxError(f"Unable to read prompt file: {parsed['prompt_file']}") from error
+
+
+def _run_usage_payload():
+    return {
+        "input_tokens": None,
+        "output_tokens": None,
+        "reasoning_tokens": None,
+        "total_tokens": None,
+    }
+
+
+def _run_cdx_error_code(error):
+    message = str(error)
+    if message.startswith("Usage:"):
+        return "invalid_request"
+    if message.startswith("Invalid cwd:"):
+        return "invalid_cwd"
+    if message.startswith("Session is disabled:"):
+        return "session_disabled"
+    if "CLI not found on PATH" in message:
+        return "provider_cli_not_found"
+    if message.startswith("Failed to start "):
+        return "provider_start_failed"
+    if (
+        message.startswith("Unsupported reasoning effort:")
+        or message.startswith("Unsupported power:")
+        or "--reasoning-effort and --power must match" in message
+    ):
+        return "invalid_reasoning_effort"
+    return "cdx_error"
+
+
+def _run_result_payload(ok, parsed, session, run_info=None, error=None, error_source=None, error_code=None):
+    run_info = run_info or {}
+    return {
+        "schema_version": API_SCHEMA_VERSION,
+        "ok": bool(ok),
+        "action": "run",
+        "session": session.get("name") if session else None,
+        "provider": session.get("provider") if session else parsed.get("provider"),
+        "model": parsed.get("model") or ((session.get("launch") or {}).get("model") if session else None),
+        "reasoning_effort": parsed.get("reasoning_effort") or ((session.get("launch") or {}).get("reasoning_effort") if session else None),
+        "power": parsed.get("power") or ((session.get("launch") or {}).get("power") if session else None),
+        "cwd": os.path.abspath(parsed.get("cwd") or os.getcwd()),
+        "run_id": run_info.get("run_id"),
+        "exit_code": run_info.get("returncode"),
+        "duration_seconds": (run_info.get("duration_ms") / 1000.0) if run_info.get("duration_ms") is not None else None,
+        "transcript_path": run_info.get("transcript_path"),
+        "stdout_path": run_info.get("stdout_path"),
+        "stderr_path": run_info.get("stderr_path"),
+        "usage": _run_usage_payload(),
+        "warnings": [],
+        "error": None if ok else {
+            "source": error_source or "cdx",
+            "code": error_code or "cdx_error",
+            "message": str(error) if error else "Run failed.",
+            "provider_code": run_info.get("returncode") if error_source == "provider" else None,
+        },
+    }
+
+
+def handle_run(rest, ctx):
+    try:
+        parsed = _parse_run_args(rest)
+        session = None
+        if parsed["name"]:
+            session = ctx["service"]["get_session"](parsed["name"])
+            if not session:
+                raise CdxError(f"Unknown session: {parsed['name']}")
+            if session.get("enabled", True) is False:
+                raise CdxError(f"Session is disabled: {parsed['name']}")
+        else:
+            selected = _select_headless_session(
+                ctx,
+                parsed["provider"],
+                min_reasoning_effort=parsed["reasoning_effort"],
+                require_ready=True,
+                force_refresh=False,
+            )
+            if not selected:
+                _write_json(ctx, _json_failure(
+                    "run",
+                    "no_suitable_session",
+                    "No suitable session found.",
+                    provider=parsed["provider"],
+                ))
+                return 1
+            session = selected["session"]
+
+        cwd = os.path.abspath(parsed["cwd"])
+        if not os.path.isdir(cwd):
+            raise CdxError(f"Invalid cwd: {parsed['cwd']}")
+        prompt = _read_run_prompt(parsed)
+        launch_updates = {}
+        if parsed.get("model"):
+            launch_updates["model"] = parsed["model"]
+        if parsed.get("permission"):
+            launch_updates["permission"] = parsed["permission"]
+        if parsed.get("reasoning_effort"):
+            launch_updates["reasoning_effort"] = parsed["reasoning_effort"]
+            launch_updates["power"] = parsed["reasoning_effort"]
+        run_session = {
+            **session,
+            "launch": {
+                **(session.get("launch") or {}),
+                **launch_updates,
+            },
+        }
+        _ensure_session_authentication(
+            run_session,
+            ctx["service"],
+            spawn=ctx.get("spawn"),
+            spawn_sync=ctx.get("spawn_sync"),
+            env_override=ctx.get("env"),
+            stdin_is_tty=False,
+            behavior="launch",
+            signal_emitter=ctx.get("signal_emitter"),
+        )
+        run_info = _run_headless_provider_command(
+            run_session,
+            cwd=cwd,
+            env_override=ctx.get("env"),
+            initial_prompt=prompt,
+            timeout_seconds=parsed.get("timeout_seconds"),
+            spawn=ctx.get("spawn_headless") or ctx.get("spawn"),
+        )
+        ok = run_info.get("returncode") == 0
+        if ok:
+            ctx["service"]["record_launch_history"](session["name"], {
+                "status": "success",
+                "cwd": cwd,
+                "exit_code": 0,
+                **run_info,
+            })
+            _write_json(ctx, _run_result_payload(True, parsed, run_session, run_info=run_info))
+            return 0
+        message = "Provider process timed out." if run_info.get("timed_out") else "Provider process exited with a non-zero status."
+        error = CdxError(message, run_info.get("returncode") or 1)
+        ctx["service"]["record_launch_history"](session["name"], {
+            "status": "failed",
+            "cwd": cwd,
+            "error": str(error),
+            "exit_code": error.exit_code,
+            **run_info,
+        })
+        _write_json(ctx, _run_result_payload(
+            False,
+            parsed,
+            run_session,
+            run_info=run_info,
+            error=error,
+            error_source="provider",
+            error_code="provider_timeout" if run_info.get("timed_out") else "provider_failed",
+        ))
+        return error.exit_code or 1
+    except CdxError as error:
+        run_info = getattr(error, "run_info", None)
+        _write_json(ctx, _run_result_payload(
+            False,
+            locals().get("parsed", {}) or {},
+            locals().get("session"),
+            run_info=run_info,
+            error=error,
+            error_source="cdx",
+            error_code=_run_cdx_error_code(error),
+        ))
+        return error.exit_code
+
+
 def _format_launch_config(session):
     launch = session.get("launch") or {}
     return "\n".join([
@@ -1033,6 +1376,7 @@ def _format_launch_config(session):
         f"permission: {launch.get('permission') or 'default'}",
         f"fast:       {'on' if launch.get('fast') is True else 'off' if launch.get('fast') is False else 'default'}",
         f"model:      {launch.get('model') or 'default'}",
+        f"priority:   {launch.get('priority') if launch.get('priority') is not None else 'default'}",
     ])
 
 
@@ -1062,6 +1406,87 @@ def _resolve_bulk_launch_targets(parsed, service):
     return targets
 
 
+def _reasoning_rank(value):
+    order = {"low": 0, "medium": 1, "high": 2, "xhigh": 2, "max": 2}
+    return order.get(str(value or "low").lower(), 0)
+
+
+def _session_reasoning_effort(session):
+    launch = session.get("launch") or {}
+    return (
+        launch.get("reasoning_effort")
+        or launch.get("reasoningEffort")
+        or launch.get("power")
+        or ("low" if launch.get("fast") is True else None)
+        or "low"
+    )
+
+
+def _session_selection_priority(session):
+    launch = session.get("launch") or {}
+    try:
+        return int(launch.get("priority") or 0)
+    except (TypeError, ValueError):
+        return 0
+
+
+def _row_blocks_ready(row):
+    if row.get("provider") in (PROVIDER_ANTIGRAVITY, PROVIDER_OLLAMA):
+        auth = "n/a"
+    else:
+        auth = row.get("auth_status") or "unknown"
+    if auth not in ("authenticated", "n/a"):
+        return True
+    available = row.get("available_pct")
+    if available is not None:
+        try:
+            if float(available) <= 0:
+                return True
+        except (TypeError, ValueError):
+            return True
+    return False
+
+
+def _select_headless_session(ctx, provider, min_reasoning_effort=None, require_ready=False, force_refresh=False):
+    sessions = [
+        session for session in ctx["service"]["list_sessions"]()
+        if session.get("provider") == provider and session.get("enabled", True) is not False
+    ]
+    minimum = _reasoning_rank(min_reasoning_effort)
+    sessions = [
+        session for session in sessions
+        if _reasoning_rank(_session_reasoning_effort(session)) >= minimum
+    ]
+    rows = ctx["service"]["get_status_rows"](force_refresh=force_refresh)
+    row_by_name = {row.get("session_name"): row for row in rows}
+    candidates = []
+    for session in sessions:
+        row = row_by_name.get(session["name"], {})
+        if require_ready and _row_blocks_ready(row):
+            continue
+        available = row.get("available_pct")
+        try:
+            available_sort = float(available) if available is not None else -1.0
+        except (TypeError, ValueError):
+            available_sort = -1.0
+        cooldown_sort = 1 if available_sort > 0 else 0
+        candidates.append({
+            "session": session,
+            "row": row,
+            "sort_key": (
+                -cooldown_sort,
+                -available_sort,
+                -_session_selection_priority(session),
+                _reasoning_rank(_session_reasoning_effort(session)),
+                session["name"],
+            ),
+        })
+    if not candidates:
+        return None
+    candidates.sort(key=lambda item: item["sort_key"])
+    return candidates[0]
+
+
 def _format_bulk_launch_summary(sessions):
     names = [session["name"] for session in sessions]
     if len(names) <= 8:

package/src/provider_runtime.py

@@ -6,6 +6,7 @@ import shlex
 import shutil
 import subprocess
 import sys
+import uuid
 from datetime import datetime, timezone
 
 from .config import PROVIDER_ANTIGRAVITY, PROVIDER_CLAUDE, PROVIDER_CODEX, PROVIDER_OLLAMA
@@ -13,6 +14,7 @@ from .errors import CdxError
 
 
 LOG_ROTATE_BYTES = 10 * 1024 * 1024  # 10 MB
+REASONING_EFFORT_VALUES = {"low", "medium", "high"}
 LAUNCH_PERMISSION_ARGS = {
     PROVIDER_CLAUDE: {
         "review": ["--permission-mode", "plan"],
@@ -158,7 +160,7 @@ def _build_launch_transcript_path(session):
 
 def _launch_power(session):
     launch = session.get("launch") or {}
-    power = launch.get("power")
+    power = launch.get("reasoning_effort") or launch.get("reasoningEffort") or launch.get("power")
     if power:
         return power
     if launch.get("fast") is True:
@@ -166,6 +168,28 @@ def _launch_power(session):
     return None
 
 
+def _normalize_reasoning_effort(reasoning_effort=None, power=None, usage="Unsupported reasoning effort."):
+    effort = str(reasoning_effort).strip().lower() if reasoning_effort is not None else None
+    alias = str(power).strip().lower() if power is not None else None
+    if effort == "":
+        raise CdxError(usage)
+    if alias == "":
+        raise CdxError(usage)
+    if effort and effort not in REASONING_EFFORT_VALUES:
+        raise CdxError(f"Unsupported reasoning effort: {reasoning_effort}")
+    if alias and alias not in REASONING_EFFORT_VALUES:
+        raise CdxError(f"Unsupported power: {power}")
+    if effort and alias and effort != alias:
+        raise CdxError("--reasoning-effort and --power must match when both are provided.")
+    resolved = effort or alias
+    if not resolved:
+        return {}
+    return {
+        "reasoning_effort": resolved,
+        "power": resolved,
+    }
+
+
 def _launch_config_args(session):
     launch = session.get("launch") or {}
     args = []
@@ -254,7 +278,7 @@ def _default_script_args(transcript_path, spec):
     return ["-q", "-F", transcript_path, spec["command"]] + spec["args"]
 
 
-def _build_launch_spec(session, cwd=None, env_override=None, initial_prompt=None):
+def _build_launch_spec(session, cwd=None, env_override=None, initial_prompt=None, capture_transcript=True):
     if initial_prompt is not None:
         if not isinstance(initial_prompt, str):
             raise CdxError("initial_prompt must be a string.")
@@ -280,7 +304,7 @@ def _build_launch_spec(session, cwd=None, env_override=None, initial_prompt=None
                 "env": claude_env,
             },
             "label": "claude",
-        }, env=env)
+        }, capture_transcript=capture_transcript, env=env)
     if session["provider"] == PROVIDER_ANTIGRAVITY:
         args = _launch_config_args(session)
         if initial_prompt:
@@ -293,7 +317,7 @@ def _build_launch_spec(session, cwd=None, env_override=None, initial_prompt=None
                 "env": {**env, **_antigravity_env_overrides(_get_auth_home(session))},
             },
             "label": "antigravity",
-        }, env=env)
+        }, capture_transcript=capture_transcript, env=env)
     if session["provider"] == PROVIDER_OLLAMA:
         launch = session.get("launch") or {}
         model = launch.get("model") or session["name"]
@@ -309,7 +333,7 @@ def _build_launch_spec(session, cwd=None, env_override=None, initial_prompt=None
                 "env": ollama_env,
             },
             "label": "ollama",
-        }, env=env)
+        }, capture_transcript=capture_transcript, env=env)
     args = ["--no-alt-screen", "--cd", cwd] + _launch_config_args(session)
     if initial_prompt:
         args.append(initial_prompt)
@@ -320,7 +344,132 @@ def _build_launch_spec(session, cwd=None, env_override=None, initial_prompt=None
             "env": {**env, "CODEX_HOME": _get_auth_home(session)},
         },
         "label": "codex",
-    }, env=env)
+    }, capture_transcript=capture_transcript, env=env)
+
+
+def _headless_artifact_paths(session, run_id=None):
+    run_id = run_id or uuid.uuid4().hex
+    log_dir = _get_launch_transcript_dir(session)
+    os.makedirs(log_dir, exist_ok=True)
+    prefix = os.path.join(log_dir, f"cdx-run-{run_id}")
+    return {
+        "run_id": run_id,
+        "transcript_path": os.path.abspath(f"{prefix}.log"),
+        "stdout_path": os.path.abspath(f"{prefix}.stdout.log"),
+        "stderr_path": os.path.abspath(f"{prefix}.stderr.log"),
+    }
+
+
+def _combine_headless_transcript(paths):
+    transcript_path = paths["transcript_path"]
+    with open(transcript_path, "w", encoding="utf-8", errors="replace") as transcript:
+        for label, path_key in (("stdout", "stdout_path"), ("stderr", "stderr_path")):
+            path = paths.get(path_key)
+            if not path:
+                continue
+            transcript.write(f"--- {label} ---\n")
+            try:
+                with open(path, "r", encoding="utf-8", errors="replace") as handle:
+                    content = handle.read()
+            except OSError:
+                content = ""
+            transcript.write(content)
+            if content and not content.endswith("\n"):
+                transcript.write("\n")
+
+
+def _headless_run_info(paths, spec, start_time, returncode):
+    end_time = datetime.now(timezone.utc)
+    return {
+        **paths,
+        "started_at": start_time.isoformat().replace("+00:00", "Z"),
+        "ended_at": end_time.isoformat().replace("+00:00", "Z"),
+        "duration_ms": int((end_time - start_time).total_seconds() * 1000),
+        "command": spec.get("command"),
+        "args": list(spec.get("args") or []),
+        "label": spec.get("label"),
+        "pid": None,
+        "returncode": returncode,
+        "timed_out": False,
+    }
+
+
+def _run_headless_provider_command(session, cwd=None, env_override=None, initial_prompt=None,
+                                   timeout_seconds=None, spawn=None, run_id=None):
+    spawn = spawn or subprocess.Popen
+    spec = _build_launch_spec(
+        session,
+        cwd=cwd,
+        env_override=env_override,
+        initial_prompt=initial_prompt,
+        capture_transcript=False,
+    )
+    paths = _headless_artifact_paths(session, run_id=run_id)
+    start_time = datetime.now(timezone.utc)
+    command = spec["command"]
+    if spawn is subprocess.Popen:
+        command = _resolve_command(command, spec.get("options", {}).get("env"))
+
+    child = None
+    timed_out = False
+    with open(paths["stdout_path"], "w", encoding="utf-8", errors="replace") as stdout_file, \
+            open(paths["stderr_path"], "w", encoding="utf-8", errors="replace") as stderr_file:
+        try:
+            child = spawn(
+                [command] + spec["args"],
+                stdout=stdout_file,
+                stderr=stderr_file,
+                **{k: v for k, v in spec.get("options", {}).items() if k not in ("stdio", "stdout", "stderr")},
+            )
+        except FileNotFoundError as error:
+            _combine_headless_transcript(paths)
+            cdx_error = CdxError(f"{spec['label']} CLI not found on PATH: {spec['command']}", 127)
+            cdx_error.run_info = _headless_run_info(paths, spec, start_time, 127)
+            raise cdx_error from error
+        except OSError as error:
+            _combine_headless_transcript(paths)
+            cdx_error = CdxError(f"Failed to start {spec['label']}: {error}", 126)
+            cdx_error.run_info = _headless_run_info(paths, spec, start_time, 126)
+            raise cdx_error from error
+        try:
+            if timeout_seconds is None:
+                child.wait()
+            else:
+                child.wait(timeout=timeout_seconds)
+        except TypeError:
+            child.wait()
+        except subprocess.TimeoutExpired:
+            timed_out = True
+            try:
+                child.terminate()
+                child.wait(timeout=5)
+            except Exception:
+                try:
+                    child.kill()
+                except Exception:
+                    pass
+                try:
+                    child.wait()
+                except Exception:
+                    pass
+
+    _combine_headless_transcript(paths)
+    end_time = datetime.now(timezone.utc)
+    returncode = getattr(child, "returncode", None) if child is not None else None
+    if timed_out and (returncode is None or returncode == 0):
+        returncode = 124
+    return {
+        **paths,
+        "started_at": start_time.isoformat().replace("+00:00", "Z"),
+        "ended_at": end_time.isoformat().replace("+00:00", "Z"),
+        "duration_ms": int((end_time - start_time).total_seconds() * 1000),
+        "command": spec.get("command"),
+        "args": list(spec.get("args") or []),
+        "label": spec.get("label"),
+        "pid": getattr(child, "pid", None),
+        "returncode": returncode,
+        "timed_out": timed_out,
+    }
 
 
 def _build_login_status_spec(session, env_override=None):

package/src/session_service.py

@@ -40,6 +40,8 @@ RESERVED_SESSION_NAMES = {
     "ren",
     "rename",
     "rmv",
+    "run",
+    "select",
     "config",
     "set",
     "status",
@@ -54,8 +56,11 @@ RESERVED_SESSION_NAMES = {
 STATUS_CACHE_TTL_SECONDS = 60
 CLAUDE_STATUS_CACHE_TTL_SECONDS = 10 * 60
 LAUNCH_POWER_VALUES = {"low", "medium", "high", "xhigh", "max"}
+LAUNCH_REASONING_EFFORT_VALUES = {"low", "medium", "high"}
 LAUNCH_PERMISSION_VALUES = {"review", "default", "auto", "full"}
 MAX_LAUNCH_MODEL_LENGTH = 128
+MIN_LAUNCH_PRIORITY = 0
+MAX_LAUNCH_PRIORITY = 100
 
 
 def _encode(name):
@@ -96,6 +101,11 @@ def _normalize_launch_settings(settings):
         if power not in LAUNCH_POWER_VALUES:
             raise CdxError(f"Unsupported power: {settings['power']}")
         normalized["power"] = power
+    if "reasoning_effort" in settings and settings["reasoning_effort"] is not None:
+        effort = str(settings["reasoning_effort"]).strip().lower()
+        if effort not in LAUNCH_REASONING_EFFORT_VALUES:
+            raise CdxError(f"Unsupported reasoning effort: {settings['reasoning_effort']}")
+        normalized["reasoning_effort"] = effort
     if "permission" in settings and settings["permission"] is not None:
         permission = str(settings["permission"]).strip().lower()
         if permission not in LAUNCH_PERMISSION_VALUES:
@@ -120,6 +130,14 @@ def _normalize_launch_settings(settings):
         if len(model) > MAX_LAUNCH_MODEL_LENGTH or any(ord(ch) < 32 or ord(ch) == 127 for ch in model):
             raise CdxError("Model contains unsupported characters.")
         normalized["model"] = model
+    if "priority" in settings and settings["priority"] is not None:
+        try:
+            priority = int(settings["priority"])
+        except (TypeError, ValueError) as error:
+            raise CdxError(f"Unsupported priority: {settings['priority']}") from error
+        if priority < MIN_LAUNCH_PRIORITY or priority > MAX_LAUNCH_PRIORITY:
+            raise CdxError(f"Unsupported priority: {settings['priority']}")
+        normalized["priority"] = priority
     return normalized
 
 
@@ -773,7 +791,7 @@ def create_session_service(options=None):
             raise CdxError(f"Unknown session: {name}")
         if not keys:
             raise CdxError("At least one launch setting is required.")
-        allowed = {"power", "permission", "fast", "model"}
+        allowed = {"power", "permission", "fast", "model", "priority"}
         unknown = [key for key in keys if key not in allowed]
         if unknown:
             raise CdxError(f"Unsupported launch setting: {', '.join(unknown)}")