cdx-manager 0.26.7 → 0.26.8

package/README.md

@@ -4,7 +4,7 @@
 
 <br clear="left"/>
 
-[![License](https://img.shields.io/badge/license-MIT-4C8BF5)](LICENSE) ![Version](https://img.shields.io/badge/version-v0.26.7-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.26.8-4C8BF5) ![Python](https://img.shields.io/badge/python-3.9%2B-3776AB?logo=python&logoColor=white)
 
 **The right AI coding account, when you need it.** CDX Manager keeps your Codex and Claude accounts in separate profiles, shows which ones have quota, and helps you pick the next usable session from your terminal.
 
@@ -120,6 +120,14 @@ cdx run work --cwd /path/to/repo --prompt "Implement the change" --reasoning-eff
 cdx run --continue-run RUN_ID --cwd /path/to/repo --prompt "Fix the remaining test failure" --json
 ```
 
+Pass provider arguments for a single run with `--extra-args 'ARGS'`. They use the session setting's POSIX quoting and validation (nonempty, at most 512 characters, no control characters, balanced quotes), and are appended after the profile's `extra_args`. They do not change the profile or subsequent interactive launches. Provider flag semantics remain unvalidated, as listed under `unvalidated.extra_args` in `cdx schema --json`; existing provider permission and workspace isolation handling still applies. Codex headless launches retain their existing behavior of ignoring session and run extra arguments.
+
+```bash
+cdx run claude-work --cwd /path/to/repo --permission default --prompt 'Run: touch t' --extra-args '--allowedTools "Bash(touch t)" --strict-mcp-config' --json
+```
+
+This allows the requested Claude tool and restricts MCP configuration for this run only. The option also follows detached runs and profile failover. With `--continue-run`, Claude extra arguments that override model, effort or conversation are refused, whether supplied by the session or this run.
+
 `--continue-run` resumes the exact Claude session or Codex thread and pins the previous run's recorded model and effort, even if the profile settings changed. The profile is inferred from the parent; an explicit session or provider must match. An explicit model or effort must also match. Runs and history record `parent_run_id` and `conversation_id`. Detached continuations use the cdx child supervisor with the same pins. Codex continuation usage is measured between exact transcript snapshots before and after the run, since exec resume can report conversation totals. If either boundary is unavailable, per-run usage stays unknown with `usage_attribution: "continuation_usage_unavailable"` in history instead of counting earlier turns again.
 
 Headless runs, including detached, remote and continued runs, keep their

package/VERSION

@@ -1 +1 @@
-0.26.7
+0.26.8

package/changelogs/CHANGELOGS_0_26_8.md

@@ -0,0 +1,19 @@
+# CDX Manager 0.26.8
+
+Release date: 2026-11-07
+
+## Improvements
+
+- Resolve the conversation of a live Codex process (#125,
+  `2150671b`). `cdx conversation <profile> --pid PID` and
+  `--process-identity ID` read the exact conversation of a native Codex
+  process, without falling back to workspace or recency matching.
+- Add per-run provider arguments to `cdx run` (#120, `92620af`).
+  `--extra-args 'ARGS'` is validated like the session setting and appended
+  after the profile's arguments, without changing saved settings or
+  interactive launches.
+
+## Maintenance
+
+- Record tray companion checksums for v0.26.7 (`bd53cb9`).
+- Record release archive checksums for v0.26.7 (`145ec42`).

package/changelogs/CHANGELOGS_UNRELEASED.md

@@ -1,5 +1,10 @@
 # Unreleased
 
+## Per-run provider arguments (#120)
+
+- Add `cdx run --extra-args 'ARGS'` with the session setting's validation and POSIX splitting, appended after the selected profile's arguments without changing saved settings or interactive launches. Preserve existing provider permission and isolation handling.
+- Forward run arguments to detached supervisors and profile failover; reject Claude model, effort and conversation overrides during continuation. List the option under `cdx schema --json` unvalidated arguments and cover run-only Claude tool allowlists and strict MCP configuration.
+
 ## Claude profile quota status line
 
 - Install a fast cache-only status line for Claude profiles at creation, settings updates and interactive launch/resume. Show the shared launcher gauge, both remaining windows, profile name, low-quota resets and a stale marker; use `quota ?` when data is unavailable.

package/checksums/release-archives.json

@@ -870,6 +870,17 @@
         "x86_64-pc-windows-msvc": "82fcceda389ba33ef60bc01ccce62249c0a1866479611192761778646ad33880",
         "x86_64-unknown-linux-musl": "a1194dc6e672729e7d6ba079b7c1a393e7098e83edd6ab3b6fd63832a7dad136"
       }
+    },
+    "v0.26.7": {
+      "github_tarball_sha256": "26e961c60c2473946cb5bfadec467b4d4ca9fd5a07cd313145cf4c4d427b1239",
+      "github_zip_sha256": "324c8f938f037e19c31b19e9fc6d4721ca822a7aa9a14d8e0e1af8da52aafaad",
+      "tray_assets": {
+        "aarch64-apple-darwin": "80088939f95fb6508f98b1e9a29643372dcc5e4cb2f72f06c5016f1708f6f526",
+        "aarch64-unknown-linux-musl": "29a044fa1241f38ce2892bd37388258ab1f10d66a74c3beef6462d85a8ab52c2",
+        "x86_64-apple-darwin": "d32be4180b361195ec9faef888dc9ff1a996bb74295882008ccb2b07dd16789d",
+        "x86_64-pc-windows-msvc": "098c27b535f041b72b6aac89d2c34464a986178be881336b89f99c8dfb5fdb5d",
+        "x86_64-unknown-linux-musl": "195737be7f25dc30bab676f53aed2c426612aee55de4cfc95a55a5b2d8ca9b76"
+      }
     }
   }
 }

package/docs/cli.md

@@ -58,7 +58,7 @@
 | `cdx agents [--max-age-hours N] [--json]` | Each session's last known agent state (working, waiting, done, failed, limit, ended), waiting first; records older than N hours (default 24) are dropped. See [Agent state](sessions-and-notifications.md#agent-state) |
 | `cdx next [--json] [--refresh]` | Select the best next assistant using the same priority logic as `cdx status` |
 | `cdx select --provider PROVIDER [--min-reasoning-effort minimal\|low\|medium\|high\|xhigh] [--min-power minimal\|low\|medium\|high\|xhigh] [--require-ready] [--refresh] --json` | Select a suitable session for headless automation |
-| `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 MODE] [--timeout-seconds N] [--budget USD] [--label TEXT] [--max-parallel N] [--continue-run RUN_ID] [--detach] [--failover] [--refresh] --json` | Run one headless task and return a stable JSON result; `--detach` returns the `run_id` at launch without waiting, `--failover` continues the task on the next account when this one hits its rate limit (with `--detach` too: the detached cdx child applies it and the run's `occupancies` record each move), `--prompt-file -` reads the prompt from stdin, `--label` names the run in `cdx runs`, `--max-parallel N` (default `CDX_MAX_RUNS`; unset, invalid, 0 or negative means no limit) refuses to start with `too_many_runs` when N runs are already running, `--kind` (default `assistant`) labels the run record and `code-review` adds a review report to its final payload |
+| `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 MODE] [--timeout-seconds N] [--budget USD] [--extra-args 'ARGS'] [--label TEXT] [--max-parallel N] [--continue-run RUN_ID] [--detach] [--failover] [--refresh] --json` | Run one headless task and return a stable JSON result; `--detach` returns the `run_id` at launch without waiting, `--failover` continues the task on the next account when this one hits its rate limit (with `--detach` too: the detached cdx child applies it and the run's `occupancies` record each move), `--prompt-file -` reads the prompt from stdin, `--label` names the run in `cdx runs`, `--max-parallel N` (default `CDX_MAX_RUNS`; unset, invalid, 0 or negative means no limit) refuses to start with `too_many_runs` when N runs are already running, `--kind` (default `assistant`) labels the run record and `code-review` adds a review report to its final payload |
 | `cdx run-report <run_id> --json` | Full report, transcript metadata, and final payload for a run; `final_message` is the run's last assistant message, read from Claude's `result` envelope or Codex's last `agent_message` (null when neither exists) |
 | `cdx run-status <run_id> --json` | Status of one run by id |
 | `cdx run-tail <run_id> [--lines N] --json` | Last lines of a run's own output, while it is still running or after it finished |
@@ -683,3 +683,75 @@ Interactive launches appear as `status: "running"` as soon as the provider start
 History entries expose `conversation_id` and `provider_transcript_match: "conversation_id"` when an exact provider transcript exists. Claude uses its launch session ID; Codex can recover a unique thread from transcript metadata matching the launch directory and time window. Ambiguous discovery remains `provider_transcript_match: "recency"`, an explicitly unverified fallback that must not be treated as a verified resume target. A known ID with no transcript does not borrow another conversation. Existing history is enriched on read without rewriting old rows.
 
 `first_user_prompt` contains the first real user text (up to 2,000 characters) from a bounded, redacted transcript read. Provider command wrappers, system reminders, tool results and bare absolute file paths are skipped. Missing, oversized or unavailable evidence leaves the prompt unknown; a supplied initial prompt is used when available.
+
+### Resolve the conversation of a live Codex process
+
+Consumers such as remote-ops can request process-scoped resolution without
+falling back to workspace/recency:
+
+```bash
+cdx conversation work2 --pid 12345 --tail 20 --json
+cdx conversation work2 --process-identity 'linux:12345:<opaque digest from response>' --json
+```
+
+Supply the native Codex PID, not the shell, tmux pane PID, Node launcher, or CDX
+supervisor. CDX does not traverse descendants or choose between processes.
+`work2` supplies the provider/profile boundary; its saved conversation is ignored
+in process mode. The selectors are mutually exclusive and cannot be combined with
+`--conversation`, `--cwd`, or `--since`.
+
+The Python API is `read_conversation("codex", auth_home, pid=12345, tail=20)` in
+`cdx_manager.conversation` (`src.conversation` in a source checkout). Retain
+`process_identity` and pass it instead of `pid` on later calls to reject PID reuse.
+A bare PID identifies its current occupant, not a previously observed process.
+The opaque identity is a lifetime guard, not an authorization grant.
+
+Process-selected pages expose:
+
+| Field | Current contract |
+| --- | --- |
+| `resolution_status` | `unknown` until native selected-conversation evidence is available |
+| `resolution_method` | `null`; kernel process identity alone is not a conversation resolution method |
+| `conversation_id` | `null`; no candidate or guessed ID is exposed |
+| `process_identity` | Opaque Linux lifetime guard when process validation succeeds |
+| `reason` | Explicit evidence boundary or process validation failure |
+
+**Current measured boundary:** process-to-selected-conversation resolution is not
+available. Even a sole open writable rollout proves only that a process owns a
+thread. During a TUI conversation switch it may belong to a retained thread while
+the selected thread has no rollout yet. Resume argv, session/profile state, cwd,
+mtime, a unique new transcript, and fuzzy text also cannot prove the current
+selection. This implementation deliberately returns
+`native_conversation_identity_unavailable` after validating a live Codex process;
+it does not claim that an open file establishes the selected conversation.
+Remote-ops must treat this as an explicit unknown, never retry via recency.
+
+Process mode returns `status: "unavailable"`, empty entries, null conversation ID
+and no cursors. With `--cursor` or `--before`, it returns `reset_required` and no
+entries: a cursor from an explicit-ID or recency lookup cannot cross into process
+mode. No process cursor is issued until it can be bound to both a verified process
+lifetime and a native conversation selection/generation. Existing explicit-ID,
+recency, forward, tail and backward pagination contracts remain unchanged.
+
+Only Linux `/proc` process identity is currently supported. Each validation reads
+at most 8 KiB each from process `stat`, `status` and kernel `boot_id`, twice, plus
+the executable symlink/stat. The guard includes PID, start ticks, boot ID, all
+four target UIDs and executable device/inode. Wrong user, a non-`codex` executable,
+dead/reused PID, inaccessible/oversized/malformed evidence, or unsupported
+provider/platform fails closed. Other reasons include `unrelated_user`,
+`unrelated_process`, `process_not_running`, `process_identity_changed`,
+`native_evidence_unavailable`, `evidence_limit`, and
+`unsupported_process_resolution`. No argv, environment, credential store,
+transcript file, directory scan or history database is read in process mode.
+A process identity does not prove profile ownership; missing native profile and
+thread association therefore remains unknown even for an existing profile.
+
+The smallest required launch-time tracking is a provider-native event containing
+the selected conversation ID on fresh start, resume and every selection change.
+The launcher must bind each event atomically to the child's boot ID/PID/start ticks,
+profile and a monotonic selection generation; invalidate it on exit. A future
+resolver can consume that bounded record and bind cursors to the same generation.
+An original resume ID or launch timestamp alone is insufficient. No launch/resume
+flags or dependencies are changed here; implementing this requires a verified
+provider lifecycle event source, which the inspected interactive interface does
+not supply. See the mission fragment for the local native probe and Tower checks.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "cdx-manager",
-  "version": "0.26.7",
+  "version": "0.26.8",
   "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.26.7"
+version = "0.26.8"
 description = "Terminal session manager for Codex and Claude accounts."
 readme = "README.md"
 requires-python = ">=3.9.2"

package/src/cli.py

@@ -273,7 +273,7 @@ def _print_help(use_color=False):
         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> [--project PATH] [--conversation <id>] [--json]', '36', use_color)}",
-        f"  {_style('cdx conversation <name> [--conversation ID] [--cwd PATH] [--since ISO] [--cursor CURSOR | --tail N | --before CURSOR] [--limit N] --json', '36', use_color)}",
+        f"  {_style('cdx conversation <name> [--conversation ID | --pid PID | --process-identity ID] [--cwd PATH] [--since ISO] [--cursor CURSOR | --tail N | --before CURSOR] [--limit N] --json', '36', use_color)}",
         f"  {_style('cdx can-resume <name> [--conversation <id>] [--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)}",

package/src/cli_args.py

@@ -22,6 +22,7 @@ from .config import (
 )
 from .errors import CdxArgumentError, CdxError
 from .provider_runtime import _normalize_reasoning_effort
+from .session_service import _normalize_launch_settings
 
 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...]] [--check-provider-flags] [--json]"
@@ -49,7 +50,7 @@ CAN_RESUME_USAGE = "Usage: cdx can-resume <name> [--conversation <id>] [--json]"
 SESSIONS_USAGE = "Usage: cdx sessions [--all] --json"
 SELECT_USAGE = "Usage: cdx select --provider PROVIDER [--min-reasoning-effort minimal|low|medium|high|xhigh] [--min-power minimal|low|medium|high|xhigh] [--require-ready] [--refresh] --json"
 NEXT_USAGE = "Usage: cdx next [--json] [--refresh]"
-RUN_USAGE = "Usage: cdx run [session] [--remote SSH_TARGET] [--remote-prefix COMMAND] (--cwd|--dir) PATH [--project 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] [--network-access] [--isolate-workspace] [--timeout-seconds N] [--budget USD] [--label TEXT] [--max-parallel N] [--continue-run RUN_ID] [--detach] [--failover] [--refresh] --json"
+RUN_USAGE = "Usage: cdx run [session] [--remote SSH_TARGET] [--remote-prefix COMMAND] (--cwd|--dir) PATH [--project 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] [--network-access] [--isolate-workspace] [--timeout-seconds N] [--budget USD] [--extra-args 'ARGS'] [--label TEXT] [--max-parallel N] [--continue-run RUN_ID] [--detach] [--failover] [--refresh] --json"
 RUN_USAGE += "\nRemote Ollama generates text only; it is not an autonomous coding agent and does not edit the repository. Requires an installed worker model; no authentication."
 RUN_JSON_REQUIRED = "cdx run: --json is required."
 RUN_TARGET_REQUIRED = "cdx run: specify a session name or --provider PROVIDER."
@@ -505,13 +506,13 @@ def cdx_schema():
             "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.
+        # Provider flag semantics remain opaque; only the argument string's
+        # syntax and size are checked by cdx.
         "unvalidated": {
             "extra_args": {
-                "reason": "Passed to the provider CLI unchanged; cdx neither parses nor verifies these arguments.",
+                "commands": ["set", "run"],
+                "option": "--extra-args",
+                "reason": "Split into literal argv entries; cdx does not verify provider flag semantics.",
                 "not_checked_by": ["cdx schema", "cdx doctor --check-provider-flags"],
             },
         },
@@ -697,6 +698,7 @@ def _parse_run_args(args):
         "--provider": {"key": "provider", "type": "str", "default": None, "transform": _parse_run_provider},
         "--model": {"key": "model", "type": "str", "default": None},
         "--continue-run": {"key": "continue_run", "type": "str", "default": None},
+        "--extra-args": {"key": "extra_args", "type": "str", "default": None},
         "--kind": {"key": "kind", "type": "str", "default": "assistant"},
         "--reasoning-effort": {"key": "reasoning_effort", "type": "str", "default": None},
         "--power": {"key": "power", "type": "str", "default": None},
@@ -755,6 +757,7 @@ def _parse_run_args(args):
         raise CdxArgumentError("cdx run: --remote-prefix requires --remote and a nonempty command.",
                                code=ARG_CODE_INVALID_VALUE, arguments=["--remote-prefix"])
     effort = _parse_run_effort(parsed["reasoning_effort"], parsed["power"])
+    extra = _normalize_launch_settings({"extra_args": parsed["extra_args"]}).get("extra_args")
     return {
         "name": name,
         "remote": parsed["remote"],
@@ -765,6 +768,7 @@ def _parse_run_args(args):
         "prompt_file": parsed["prompt_file"],
         "prompt": parsed["prompt"],
         "continue_run": parsed["continue_run"],
+        "extra_args": extra,
         "kind": parsed["kind"],
         "model": parsed["model"],
         "permission": parsed["permission"],

package/src/commands/conversation.py

@@ -6,13 +6,15 @@ from ..conversation import read_conversation
 from ..errors import CdxError
 from ..provider_runtime import _get_auth_home
 
-CONVERSATION_USAGE = "Usage: cdx conversation <name> [--conversation ID] [--cwd PATH] [--since ISO] [--cursor CURSOR | --tail N | --before CURSOR] [--limit N] --json"
+CONVERSATION_USAGE = "Usage: cdx conversation <name> [--conversation ID | --pid PID | --process-identity ID] [--cwd PATH] [--since ISO] [--cursor CURSOR | --tail N | --before CURSOR] [--limit N] --json"
 
 
 def handle_conversation(rest, ctx):
     parsed = _parse_flag_args(rest, {
         "--json": {"key": "json", "type": "bool", "default": False},
         "--conversation": {"key": "conversation", "type": "str"},
+        "--pid": {"key": "pid", "type": "str"},
+        "--process-identity": {"key": "process_identity", "type": "str"},
         "--cwd": {"key": "cwd", "type": "str"},
         "--since": {"key": "since", "type": "str"},
         "--tail": {"key": "tail", "type": "str"},
@@ -26,15 +28,20 @@ def handle_conversation(rest, ctx):
     if not session:
         raise CdxError(f"Unknown session: {parsed['names'][0]}")
     try:
+        pid = int(parsed["pid"]) if parsed["pid"] is not None else None
         limit = int(parsed["limit"])
         tail = int(parsed["tail"]) if parsed["tail"] is not None else None
     except ValueError:
         raise CdxError(CONVERSATION_USAGE) from None
+    process_selected = parsed["pid"] is not None or parsed["process_identity"] is not None
+    if parsed["pid"] is not None and parsed["process_identity"] is not None:
+        raise CdxError(CONVERSATION_USAGE)
     page = read_conversation(
         session["provider"], _get_auth_home(session),
-        conversation_id=parsed["conversation"] or (session.get("conversation") or {}).get("id"),
+        conversation_id=parsed["conversation"] or (None if process_selected else (session.get("conversation") or {}).get("id")),
+        pid=pid, process_identity=parsed["process_identity"],
         cwd=parsed["cwd"], started_at=parsed["since"],
-        cursor=parsed["cursor"], limit=limit, tail=tail, before=parsed["before"], fallback_to_recency=not parsed["conversation"],
+        cursor=parsed["cursor"], limit=limit, tail=tail, before=parsed["before"], fallback_to_recency=not process_selected and not parsed["conversation"],
     )
     _write_json(ctx, _json_success("conversation", "Conversation page loaded.", session=session["name"], **page))
     return 0

package/src/commands/runs.py

@@ -209,6 +209,7 @@ def _detached_child_argv(parsed, prompt_path, session_name, cwd):
         ("--project", "project"),
         ("--budget", "budget"),
         ("--continue-run", "continue_run"),
+        ("--extra-args", "extra_args"),
         ("--model", "model"),
         ("--kind", "kind"),
         ("--permission", "permission"),
@@ -216,7 +217,8 @@ def _detached_child_argv(parsed, prompt_path, session_name, cwd):
     ):
         value = parsed.get(key)
         if value:
-            argv += [flag, str(value)]
+            # A literal provider flag may also be a cdx flag, so bind the value.
+            argv += [f"{flag}={value}"] if key == "extra_args" else [flag, str(value)]
     # reasoning_effort and power are normalized to the same value upstream;
     # passing one back is enough and avoids re-tripping the must-match check.
     if parsed.get("reasoning_effort"):
@@ -612,6 +614,14 @@ def _budget_observation(session, paths, baseline):
     return observation
 
 
+def _run_session(session, launch_updates, extra_args):
+    """Apply run-only settings without mutating the profile or its successors."""
+    launch = {**(session.get("launch") or {}), **launch_updates}
+    if extra_args is not None:
+        launch["extra_args"] = " ".join(value for value in (launch.get("extra_args"), extra_args) if value)
+    return {**session, "launch": launch}
+
+
 def _continue_run_session(parsed, ctx):
     """Resolve only the parent's profile and exact persisted conversation."""
     previous = _run_registry(ctx).get(parsed["continue_run"])
@@ -651,7 +661,7 @@ def _continue_run_session(parsed, ctx):
         pinned_options = {"--model", "--effort", "--fallback-model", "--resume", "--continue",
                           "--session-id", "--fork-session", "--resume-session-at", "--from-pr",
                           "--settings", "--agent", "--agents"}
-        for arg in split_extra_args((session.get("launch") or {}).get("extra_args")) or []:
+        for arg in split_extra_args(_run_session(session, {}, parsed.get("extra_args"))["launch"].get("extra_args")) or []:
             if arg.split("=", 1)[0] in pinned_options or arg.startswith(("-r", "-c")):
                 raise CdxError("--continue-run cannot use Claude extra_args that override model, effort, or conversation.",
                                code="continue_run_settings_mismatch")
@@ -767,13 +777,7 @@ def handle_run(rest, ctx):
         # the profile's current conversation. Continuations use the parent run.
         if not parsed.get("continue_run"):
             session = ctx["service"]["begin_conversation"](session["name"])
-        run_session = {
-            **session,
-            "launch": {
-                **(session.get("launch") or {}),
-                **launch_updates,
-            },
-        }
+        run_session = _run_session(session, launch_updates, parsed.get("extra_args"))
         if not parsed.get("remote"):
             _ensure_session_authentication(
                 run_session,
@@ -970,7 +974,7 @@ def handle_run(rest, ctx):
                     else:
                         selection_row = successor.get("row") or {}
                         next_session = successor["session"]
-                        run_session = {**next_session, "launch": {**(next_session.get("launch") or {}), **launch_updates}}
+                        run_session = _run_session(next_session, launch_updates, parsed.get("extra_args"))
                         # Each new profile starts with the requested model, or its own default.
                         models = capacity_models(run_session)
                         model_index = capacity_retries = 0
@@ -1025,10 +1029,7 @@ def handle_run(rest, ctx):
                 failover_error_code = "failover_exhausted"
                 break
             selection_row = successor.get("row") or {}
-            run_session = {
-                **successor["session"],
-                "launch": {**(successor["session"].get("launch") or {}), **launch_updates},
-            }
+            run_session = _run_session(successor["session"], launch_updates, parsed.get("extra_args"))
             attempted.append(run_session["name"])
             models = capacity_models(run_session)
             model_index = capacity_retries = 0

package/src/conversation.py

@@ -379,7 +379,47 @@ def _read_tail(handle, stat, identity, provider, page, count, before):
     return page
 
 
+def _validate_page_options(limit, tail, cursor, before):
+    if not isinstance(limit, int) or isinstance(limit, bool) or not 1 <= limit <= 1000:
+        raise CdxError("Conversation limit must be an integer between 1 and 1000.")
+    if tail is not None and (type(tail) is not int or not 1 <= tail <= 1000):
+        raise CdxError("Conversation tail must be an integer between 1 and 1000.")
+    if cursor is not None and (tail is not None or before is not None):
+        raise CdxError("Conversation --cursor cannot be combined with --tail or --before.")
+
+
 def read_conversation(provider, auth_home=None, *, conversation_id=None, started_at=None,
+                      terminal_transcript=None, cursor=None, limit=100, fallback_to_recency=False,
+                      tail=None, before=None, cwd=None, pid=None, process_identity=None):
+    """Read a conversation page, optionally bound to a live native process.
+
+    Process selection never uses saved session IDs or recency. Keep the returned
+    opaque process_identity for later polls to detect PID reuse. Unknown evidence
+    returns no entries. See docs/cli.md for platform and snapshot limitations.
+    """
+    _validate_page_options(limit, tail, cursor, before)
+    options = dict(conversation_id=conversation_id, started_at=started_at,
+                   terminal_transcript=terminal_transcript, cursor=cursor, limit=limit,
+                   fallback_to_recency=fallback_to_recency, tail=tail, before=before, cwd=cwd)
+    if pid is None and process_identity is None:
+        return _read_conversation_page(provider, auth_home, **options)
+    if conversation_id is not None or cwd is not None or started_at is not None or terminal_transcript is not None:
+        raise CdxError("Process selection cannot be combined with conversation, cwd, since or terminal transcript selection.")
+    from .process_conversation import resolve_process_conversation
+
+    resolution = resolve_process_conversation(provider, auth_home, pid=pid, process_identity=process_identity)
+    page = {"status": "unavailable", "provider": provider, "entries": [], "next_cursor": None,
+            "has_more": False, "resolution_scope": None, **resolution}
+    if tail is not None or before is not None:
+        page["before_cursor"] = None
+    # No process-bound cursor is issued until native selected-thread evidence
+    # exists. Never replay an explicit-ID or recency cursor through this mode.
+    if cursor is not None or before is not None:
+        page["status"] = "reset_required"
+    return page
+
+
+def _read_conversation_page(provider, auth_home=None, *, conversation_id=None, started_at=None,
                       terminal_transcript=None, cursor=None, limit=100, fallback_to_recency=False, tail=None, before=None, cwd=None):
     """Return a JSON-serializable page; pass next_cursor back unchanged to poll.
 
@@ -394,12 +434,7 @@ def read_conversation(provider, auth_home=None, *, conversation_id=None, started
     Tool bodies and reasoning blocks are never returned. Ollama PTY captures
     cannot reliably distinguish roles and are explicitly unsupported.
     """
-    if not isinstance(limit, int) or isinstance(limit, bool) or not 1 <= limit <= 1000:
-        raise CdxError("Conversation limit must be an integer between 1 and 1000.")
-    if tail is not None and (type(tail) is not int or not 1 <= tail <= 1000):
-        raise CdxError("Conversation tail must be an integer between 1 and 1000.")
-    if cursor is not None and (tail is not None or before is not None):
-        raise CdxError("Conversation --cursor cannot be combined with --tail or --before.")
+    _validate_page_options(limit, tail, cursor, before)
     if started_at is not None:
         try:
             datetime.fromisoformat(started_at.replace("Z", "+00:00"))

package/src/process_conversation.py

@@ -0,0 +1,81 @@
+"""Bounded Linux process identity, without guessing a selected conversation.
+
+No argv, environment, credential stores, transcript searches or parent/child
+heuristics participate in identity resolution.
+"""
+
+import hashlib
+import os
+import re
+import sys
+from pathlib import Path
+
+PROC_ROOT = Path("/proc")
+_UUID = r"[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}"
+_IDENTITY = re.compile(r"linux:(\d+):[0-9a-f]{64}")
+
+
+class _Unknown(Exception):
+    pass
+
+
+def _bounded(path, limit=8192):
+    with open(path, "rb") as handle:
+        value = handle.read(limit + 1)
+    if len(value) > limit:
+        raise _Unknown("evidence_limit")
+    return value.decode("utf-8")
+
+
+def _process(pid):
+    root = PROC_ROOT / str(pid)
+    fields = _bounded(root / "stat").rsplit(")", 1)[1].split()
+    if fields[0] in ("Z", "X", "x"):
+        raise _Unknown("process_not_running")
+    uids = next(line.split()[1:] for line in _bounded(root / "status").splitlines() if line.startswith("Uid:"))
+    if len(uids) != 4 or any(int(uid) != os.getuid() for uid in uids):
+        raise _Unknown("unrelated_user")
+    executable = os.readlink(root / "exe")
+    if Path(executable).name != "codex":
+        raise _Unknown("unrelated_process")
+    exe = os.stat(root / "exe")
+    boot = _bounded(PROC_ROOT / "sys/kernel/random/boot_id").strip()
+    if not re.fullmatch(_UUID, boot):
+        raise _Unknown("invalid_evidence")
+    digest = hashlib.sha256(f"{boot}:{pid}:{fields[19]}:{uids}:{exe.st_dev}:{exe.st_ino}".encode()).hexdigest()
+    return f"linux:{pid}:{digest}"
+
+
+def resolve_process_conversation(provider, auth_home, *, pid=None, process_identity=None):
+    """Return explicit unknown when the native selected-thread link is absent.
+
+    A bare PID means the process alive *now*. Persist process_identity to reject
+    reuse on subsequent calls. The identity is an opaque guard, not a secret or
+    authorization grant. Only Linux /proc and interactive Codex are supported.
+    """
+    result = {"resolution_status": "unknown", "resolution_method": None,
+              "conversation_id": None, "process_identity": None, "reason": None}
+    if provider != "codex" or sys.platform != "linux":
+        return {**result, "reason": "unsupported_process_resolution"}
+    if process_identity is not None:
+        match = _IDENTITY.fullmatch(process_identity) if isinstance(process_identity, str) and len(process_identity) <= 100 else None
+        if not match or pid is not None:
+            return {**result, "reason": "invalid_process_identity"}
+        pid = int(match[1])
+    if type(pid) is not int or not 0 < pid < 2**31 or not auth_home:
+        return {**result, "reason": "invalid_process_identity"}
+    try:
+        identity = _process(pid)
+        if process_identity is not None and identity != process_identity:
+            raise _Unknown("process_identity_changed")
+        result["process_identity"] = identity
+        if _process(pid) != identity:
+            raise _Unknown("evidence_changed")
+        # Even a sole writable rollout may belong to a retained thread while
+        # another thread is selected but has not created its rollout. Neither
+        # that descriptor nor resume argv is a native selected-thread event.
+        return {**result, "reason": "native_conversation_identity_unavailable"}
+    except _Unknown as exc:
+        return {**result, "reason": str(exc)}
+    except (OSError, ValueError, KeyError, IndexError, TypeError, StopIteration, UnicodeError, RecursionError):
+        return {**result, "reason": "native_evidence_unavailable"}