cdx-manager 0.25.1 → 0.25.3

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.25.1-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.25.3-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.
 
@@ -88,3 +88,101 @@ Recovery does not require `--failover`, which still controls account quota exhau
 - [Tray companion testing](docs/tray-local-testing.md) — local development loops.
 
 Contributions are welcome; see [CONTRIBUTING.md](CONTRIBUTING.md). CDX Manager is [MIT licensed](LICENSE).
+
+### Run Codex on an SSH worker
+
+```sh
+cdx run work --remote agent@worker --cwd /srv/project --prompt 'Run the checks' --json
+cdx run work --remote worker --cwd /srv/project --prompt-file task.txt --detach --label checks --budget 2 --json
+cdx run work --remote Spire --remote-prefix 'wsl.exe -d Ubuntu --' --cwd /srv/project --prompt 'Run the checks' --json
+```
+
+The controller remains the authority for the profile, quota, history, costs and
+run registry. Use `run-status`, `run-report` and `run-tail` on the controller with
+the returned run ID. Permission, model, reasoning effort, prompt, timeout, budget,
+label and detached execution use the existing run options. `--cwd` names an
+absolute directory on the worker; it need not exist on the controller. Files are
+not synchronized. Use `--project` to explicitly attribute a remote checkout to a
+project. Remote runs do not retry or fail over automatically, including when
+`--failover` is supplied.
+
+Requirements: a POSIX controller with `ssh` and Codex on PATH, and a Linux worker
+with Python 3, memory-backed `/dev/shm`, and exactly the same `codex --version`.
+Configure SSH keys, host trust and aliases in advance; the connection uses batch
+mode and bounded connection/keepalive timeouts. Provider refusal, unreachable
+workers and version mismatches fail before sending credentials. Only Codex OAuth
+profiles are supported. Remote continuation is refused because the temporary home
+does not preserve conversation rollouts. Codex's native permission sandbox still
+applies to ordinary remote runs.
+
+For SSH servers landing in Windows `cmd.exe` (including Spire and Citadel), pass
+`--remote-prefix 'wsl.exe -d Ubuntu --'` to enter Linux before starting Python.
+The prefix accepts plain command words, options and paths without spaces or shell
+metacharacters; it is forwarded to detached runs. POSIX targets need no prefix.
+Only a short, double-quoted Python bootstrap is sent in the SSH command line;
+the worker and shared sandbox source are framed on stdin before the payload.
+Neither source size nor prompt size consumes cmd.exe's 8191-character command limit.
+
+`--remote` supports `--isolate-workspace` using the same local isolation mechanism:
+bubblewrap, pasta (passt), nftables, Python, the checkout/toolchain allowlist,
+and an actual namespace/network setup using a dummy credential. Missing dependencies,
+namespace denial or invalid checkouts fail before sending real credentials, without
+an unisolated fallback.
+
+For **every isolated Codex run**, local or remote, the sandbox mounts only a
+run-private, mode-600 `auth.json` on verified memory-backed storage, with an empty
+`refresh_token`. It never mounts the controller profile's full authentication file.
+The controller refreshes under the authentication lock at the thresholds below
+before preparing the snapshot, then releases the lock for the run. The temporary
+home is removed after success, failure, launch errors and stop. Non-isolated local
+runs and interactive login/refresh retain their normal profile authentication.
+
+**Accepted residual risk (operator decision, 2026-11-01):** agent tools inside the
+sandbox can read the copied access token, which can remain valid for up to ten
+days. A read-only mount prevents modification, not disclosure. The rotating refresh
+token never enters the sandbox or leaves the controller. Codex was measured to run
+with an empty refresh token on 2026-11-01.
+
+A long isolated Tower mission keeps its original credential snapshot even when
+scheduled controller refresh updates the real profile. There is no authentication
+writeback or token renewal inside the sandbox. A run that outlives its access token
+fails with a clear temporary-credential expiry error and must start a new run.
+
+The controller takes the profile's authentication lock and refreshes through its
+local [Codex app-server](https://learn.chatgpt.com/docs/app-server) when `last_refresh` is older than seven days or the access
+token has less than 24 hours left. It verifies freshness after refreshing and
+fails closed if freshness or expiration cannot be established. Only
+`access_token`, `id_token`, `account_id` and `last_refresh` travel, with an empty
+`refresh_token`. The rotating refresh token never leaves the controller. The
+credential travels exclusively over SSH stdin, and is absent from command
+arguments, environment variables, run records and output. The agent receives
+`/dev/null` as stdin, not the bootstrap script or credential transport.
+
+Each worker run gets a private mode-700 home under
+`/dev/shm/cdx-remote-<uid>/run-*`, with mode-600 `auth.json` and file-only credential storage. Only non-secret scalar
+preferences (`model`, `model_reasoning_effort`, `service_tier`, `personality`,
+`model_context_window`, `model_auto_compact_token_limit`) from the top level of
+`config.toml` are copied. Hooks, custom providers, environment settings and other
+controller-local configuration are not copied. The home is removed on completion,
+failure, cancellation and SSH stdin closure. Stop a detached run by sending
+SIGTERM to the controller PID returned at launch. Uncatchable worker termination
+can leave a home behind; the next launch sweeps homes whose worker lock is no
+longer held. No persistent worker authentication is installed or refreshed.
+
+A profile occupied by a remote run is busy for local and remote runs using the
+same controller through the run registry. The authentication lock is held only
+while refreshing and validating the credential snapshot, then released before SSH
+launch. Scheduled `cdx auth refresh` and quota probes can acquire it during a long
+mission; they no longer see a mission-long `locked`/`auth_refresh_indeterminate`
+result. A probe overlapping the short snapshot can still report contention.
+Controller renewal does not extend the worker's copied access token; quota remains
+one controller-side account snapshot, never a worker copy. Multiple independent controllers sharing copied OAuth profiles are not
+supported. Costs and budget checks use measured worker usage and observed rollout
+models; unknown prices and delayed provider reporting retain the usual budget
+limitations. A run that outlives the access credential fails with
+`remote_credential_expired`, requiring a new controller launch.
+
+The empty-refresh-token behavior was measured with Codex CLI 0.166.0. Real-host
+acceptance should verify that the installed matching CLI does not attempt a
+refresh with the temporary home, that the controller token chain stays unchanged
+for a fresh credential, and that cleanup works after disconnect and SIGTERM.

package/VERSION

@@ -1 +1 @@
-0.25.1
+0.25.3

package/changelogs/CHANGELOGS_0_25_2.md

@@ -0,0 +1,15 @@
+# CDX Manager 0.25.2
+
+Release date: 2026-10-31
+
+This patch release improves usage attribution and makes unverifiable run budgets fail explicitly.
+
+## Fixes
+
+- Preserve observed Codex model evidence for usage pricing. Keep costs unknown when model evidence is missing or mixed without per-model counters, and fail unverifiable budgets with `budget_unverifiable` and exit code 125. (#76)
+- Attribute CDX usage to canonical source repositories so project statistics group runs by their source repository rather than isolated execution directories. (#75)
+
+## Maintenance
+
+- Record tray companion checksums for v0.25.1. (`e3530977b2b95cd3ec39bbe962725f275fef4370`)
+- Record release archive checksums for v0.25.1. (`59b5d276abc5877554d9ffc44b468b53b12dd1d4`)

package/changelogs/CHANGELOGS_0_25_3.md

@@ -0,0 +1,20 @@
+# CDX Manager 0.25.3
+
+Release date: 2026-11-01
+
+This patch release adds remote Codex execution over SSH and strengthens credential isolation for local and remote sandboxes.
+
+## Features
+
+- Run Codex on a Linux SSH worker with temporary credentials while keeping profiles, quota, history, costs, and run tracking on the controller. Support detached execution and clean up the temporary worker home after the run. (#78)
+
+## Fixes and security
+
+- Keep rotating refresh tokens on the controller and out of local and remote sandboxes. Use temporary access-token snapshots on verified memory-backed storage, refresh and validate credentials before launch, and fail explicitly when a snapshot expires. (#81)
+- Upgrade cryptography and pytest to address security alerts while preserving Python 3.9 compatibility through a version-specific pytest requirement. (#80)
+- Fix remote bootstrapping through Windows SSH shells and WSL without exceeding the command-line length limit. Check isolation prerequisites before sending credentials and refuse unsafe isolation without an unisolated fallback. (#79)
+
+## Maintenance
+
+- Record tray companion checksums for v0.25.2. (`4f810c3801418bc0ad8a480333cc0bdfda39383e`)
+- Record release archive checksums for v0.25.2. (`b33eba1894d9cc68d395133848beccae38589a68`)

package/changelogs/CHANGELOGS_UNRELEASED.md

@@ -1,7 +1,35 @@
 # Unreleased
 
+## Dependency security
+
+- Require cryptography >=50.0.0 for encrypted auth bundles and remove the vulnerable 47.0.0 lock entry. Python 3.9 remains supported from 3.9.2, as cryptography 50 excludes 3.9.0 and 3.9.1.
+- Require pytest >=9.0.3 in the development extra on Python >=3.10; retain the existing 9.2.0 lock entry. pytest is not a runtime dependency. Python 3.9 still uses 8.4.2, the last compatible release, and its medium-severity alert remains unresolved pending an upstream backport or a decision to drop Python 3.9 development support.
+- Check lock consistency and run the CI test matrix against locked development dependencies without upgrading unrelated packages.
+
 ## Run costs and budgets
 
 - Add nullable `cost_usd` to JSON history entries using the same observed usage, model pricing, and price overrides as stats.
 - Add `cdx run --budget USD` to stop on measured estimated spend with exit code 125, `budget_exceeded`, and `error.spent_usd` in the final JSON. Share the budget across recovery attempts and failover; support detached runs and fresh budgets for continued runs without charging earlier turns.
 - Document unknown usage/prices and delayed provider reporting, including possible budget overshoot. Cover pricing, unknown costs, validation, live process termination, Claude transcript accumulation, continuation boundaries, and detached supervision in tests.
+
+## Remote Codex runs
+
+- Add `cdx run --remote SSH_TARGET` with controller-owned supervision, registry, history, output, costs, budgets and detached execution.
+- Refresh under the controller authentication lock at the seven-day/24-hour thresholds, then send a temporary OAuth credential over SSH stdin with an empty refresh token. Refuse rotating credentials, other providers and CLI version mismatches.
+- Keep worker credentials in a private memory-backed home, clean up after success, failure and stop, and sweep dead homes on the next launch. Keep agent stdin separate from bootstrap input and report credential expiration without retrying.
+- Cover transport and credential isolation, thresholds, cleanup, sweep, unreachable workers, provider refusal and registry reports with a fake SSH worker.
+
+## Remote worker transport and isolation preflight
+
+- Add `--remote-prefix` for Windows SSH landings such as `wsl.exe -d Ubuntu --`, including detached runs. Keep the POSIX default and use a short double-quoted bootstrap on argv; send framed worker/sandbox source and then credentials/payload over stdin.
+- Probe the local bubblewrap/pasta/nftables isolation mechanism on the worker with dummy credentials, including namespace/network startup. Refuse missing dependencies or setup failures without falling back to an unisolated run.
+- Enable remote isolated Codex execution after a successful isolation probe, following the operator decision of 2026-11-01. Agent tools can read the copied access token (up to ten days of validity); missing dependencies still refuse without fallback.
+- Release the controller authentication lock after preparing the credential snapshot so scheduled authentication refresh can run during long remote missions. Keep profile mission exclusion in the run registry and the worker credential's original expiry.
+- Test cmd.exe length/quoting enforcement, Windows prefixes, large stdin payloads, POSIX transport, sanitized credential snapshots, sandbox construction/dependencies and concurrent scheduled refresh with synthetic credentials.
+
+## Isolated Codex credentials
+
+- Replace the local full-profile auth mount with a mode-600 run-private snapshot on verified memory-backed storage, containing an empty refresh token. Refresh on the controller under the auth lock at the existing seven-day/24-hour thresholds before launch.
+- Keep snapshots independent of controller refresh during long missions, prohibit authentication writeback, enforce their original expiry, and remove temporary storage after success, failure and stop. Non-isolated local authentication remains unchanged.
+- Reject rotating credentials at the sandbox boundary. Test snapshot contents, permissions, cleanup, refresh lock ownership, concurrent controller refresh, remote isolation through fake SSH and missing dependency refusal.
+- The separately maintained remote-ops `scripts/workspace_sandbox.py` requires the same credential guard and run-private lifecycle integration; it is not shipped by this repository.

package/checksums/release-archives.json

@@ -694,6 +694,28 @@
         "x86_64-pc-windows-msvc": "2493b0c8212ccdbf5e69756af07afe47c73474407f79604d671142d5192aa642",
         "x86_64-unknown-linux-musl": "53024f4908847452ce6ac399ca03725b95b628df721856da6e2ed9399691455f"
       }
+    },
+    "v0.25.1": {
+      "github_tarball_sha256": "7899a8cb3f3eb2d83d10b921a4c22c16f1d7eba4681c564b7b09812699892ad6",
+      "github_zip_sha256": "19f9646e1e74761f588b9ef195a2a90914a48ad2621a67f9d85057417db8cd19",
+      "tray_assets": {
+        "aarch64-apple-darwin": "d5d5fd19ad3a2e8bd3bcd72a959a217bbfa2fea351bcd739b94265ceb1fdd2c4",
+        "aarch64-unknown-linux-musl": "e8824cd7ec91e81bf7be1f2af53689de0aa8bbb9f7037d9e2e51fed35837a8a3",
+        "x86_64-apple-darwin": "d507a6f35894a7125cef7dc67f98e485e08774221d9dc92698c11b0f9c5354c3",
+        "x86_64-pc-windows-msvc": "183ef3664489888a356ad9a6096b68c913d433c513d6d10e9890e65667e1e417",
+        "x86_64-unknown-linux-musl": "5660cfd08c0580db43dee5664fe95fc4cd528a6495c40167e34c122d3c4fcd4a"
+      }
+    },
+    "v0.25.2": {
+      "github_tarball_sha256": "8ed02d4ce31ca6aa9669396675ee1d5b6669e80f33418c00c2a210306ea19e0d",
+      "github_zip_sha256": "0e8770a0e18c6c99bd5d845c8c54d90eb33fbf71720be89d87396eaee1632cfe",
+      "tray_assets": {
+        "aarch64-apple-darwin": "3c0cc113b70670e0f1bd9eff4589cddd8a5e3f76d7b53d7a1d66a2529f5e6e84",
+        "aarch64-unknown-linux-musl": "ff978672276fdfa8f22af8d3dadb63e0d26fa40c6f10d48f834073b08c620efd",
+        "x86_64-apple-darwin": "42323cbce340238ada8d986192d198a82e37d5958fb25b56cbaf8dba347da05c",
+        "x86_64-pc-windows-msvc": "ffcd4deb8b3843771659d2c6b92b003822b288329ddcf3b9a13f0f9820fa3df1",
+        "x86_64-unknown-linux-musl": "2cefeea0aad5bb0acfcbc99146ffacc5c5da9386f8338e4a01541e97ccf71e07"
+      }
     }
   }
 }

package/docs/cli.md

@@ -28,6 +28,7 @@
 | `cdx set <name>\|--sessions all\|a,b\|--provider PROVIDER [--power minimal\|low\|medium\|high\|xhigh] [--permission review\|default\|auto\|full] [--fast on\|off] [--rtk on\|off] [--logics on\|off] [--notify on\|off] [--agent-state on\|off] [--notify-preview on\|off] [--scrub-env on\|off] [--shared-memory on\|off] [--retro on\|off] [--policy use\|ask-first\|never] [--model MODEL] [--fallback-model MODEL[,MODEL...]] [--budget USD] [--extra-args 'ARGS'] [--priority 0..100] [--json]` | Persist launch settings for one or more sessions |
 | `cdx unset <name>\|--sessions all\|a,b\|--provider PROVIDER (--power\|--reasoning-effort\|--permission\|--fast\|--rtk\|--logics\|--notify\|--agent-state\|--notify-preview\|--scrub-env\|--shared-memory\|--retro\|--policy\|--model\|--fallback-model\|--budget\|--extra-args\|--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 history backfill-projects [--mapping FILE] [--dry-run \| --apply] [--json]` | Recover source repository attribution from exact recorded run evidence or an operator mapping; defaults to a read-only preview |
 | `cdx history backfill-models [--dry-run \| --apply] [--json]` | Recover missing historical usage models from evidence tied to each run; defaults to a read-only preview |
 | `cdx last [--json]` | Launch the most recent existing session from launch history |
 | `cdx resume <name> [--conversation <id>] [--json]` | Resume the provider-native conversation for a session using the named command form; `--conversation` reopens that exact conversation and refuses with `conversation_not_found` if the profile has no such transcript |
@@ -62,7 +63,7 @@
 | `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 |
 | `cdx runs [--limit N] [--since 7d\|today\|DATE] [--running] --json` | List recent runs; `--since` returns every run completed after the cursor and ignores `--limit`; `--running` returns every run still running, uncapped. A run's `kind` is one of the values `cdx schema --json` lists under `enums.kind` |
 | `cdx schema --json` | Publish the enums, mutually-exclusive argument groups, and error codes programmatic callers should validate against |
-| `cdx stats [name] [--since 7d\|today\|DATE] [--from DATE] [--to DATE] [--by session\|project\|model] [--json]` | Aggregate launch counts, duration, and known token usage by session, for headless and interactive runs alike. `--by project` groups runs by launch folder (labelled by the shortest trailing part that tells folders apart; `project` in JSON holds the full path), `--by model` by the model that served them (same totals, same pricing; default `session`). PROV. lists every provider a row saw, such as `claude+codex`. Without a session filter it also prints what rtk saved over the period (`rtk` in JSON), read with `rtk gain` from `RTK_DB_PATH` when set, else the shared history, and the older per-profile ones. |
+| `cdx stats [name] [--since 7d\|today\|DATE] [--from DATE] [--to DATE] [--by session\|project\|model] [--json]` | Aggregate launch counts, duration, and known token usage by session, for headless and interactive runs alike. `--by project` groups runs by the recorded canonical source repository (labelled by the shortest distinguishing path suffix; `project` in JSON holds the canonical identity, `session_name` the display label, and `-` explicitly means unknown), `--by model` by the model that served them (same totals, same pricing; default `session`). PROV. lists every provider a row saw, such as `claude+codex`. Without a session filter it also prints what rtk saved over the period (`rtk` in JSON), read with `rtk gain` from `RTK_DB_PATH` when set, else the shared history, and the older per-profile ones. |
 | `cdx status [--json] [--refresh\|--cached] [--timeout SECONDS]` | Show token usage table for all sessions; empty credits, block, and reset columns are omitted; `--cached` skips live provider probes and returns only stored status; Claude rows also report the auth type (`setup-token` or `full-login`) in a TYPE column and as `auth_type` in JSON. |
 | `cdx status --small [--refresh\|--cached] [--timeout SECONDS]` / `cdx status -s [--refresh\|--cached] [--timeout SECONDS]` | Show compact token usage table without provider, blocking quota, credits, and updated columns |
 | `cdx status <name> [--json] [--refresh\|--cached] [--timeout SECONDS]` | Show detailed usage breakdown for one session; `--cached` avoids live provider refreshes |
@@ -253,7 +254,7 @@ At or above the limit, cdx terminates the provider process tree, skips further r
 
 With `--detach`, the launch still exits successfully and includes `budget_usd`; cdx always uses its own child supervisor for budgeted runs, including when native background delegation is enabled. Inspect `cdx run-status RUN_ID --json` or `cdx run-report RUN_ID --json` for the child's final payload and budget error. `--continue-run` starts a fresh budget for the new run, including in detached mode.
 
-Conservative assumption: this is a stop based on observed, priceable usage, not a prepaid billing limit. Provider updates can arrive late or only at completion, and termination can take time, so actual spend can exceed the amount. Missing usage, missing continuation boundaries, mixed/unobserved models, and unknown prices are not treated as free tokens and cannot trigger the budget; their estimated cost stays `null`. Supply a `CDX_TOKEN_PRICES` override for a model missing from the table. Existing profile-level `cdx set --budget` settings remain the provider-native Claude cap and apply independently.
+Conservative assumption: this is a stop based on observed, priceable usage, not a prepaid billing limit. Provider updates can arrive late or only at completion, and termination can take time, so actual spend can exceed the amount. Before the first measurement, `budget_status` is `usage_not_measured`; absence is not zero spend. Once usage is measured, missing continuation boundaries, mixed/unobserved models, and unknown prices stop further execution/recovery with exit **125**, `error.source: "cdx"`, `error.code: "budget_unverifiable"`, `budget_status: "unverifiable"`, and `cost_usd: null`. This is a measurement failure, not a claim that the dollar limit was exceeded or enforced. Supply a `CDX_TOKEN_PRICES` override for a model missing from the table. Existing profile-level `cdx set --budget` settings remain the provider-native Claude cap and apply independently.
 
 Every usage record, whichever path produced it, uses one set of definitions:
 
@@ -289,6 +290,10 @@ The figure uses standard public list prices, excluding Fast/priority, Batch/Flex
 
 `cdx stats` counts completed history attempts. A headless failover has one logical run in `cdx runs` but one history row per attempted session, including failed attempts that reported usage. Period filtering includes the entire run in every period it overlaps, so adjacent daily results can both include a run crossing midnight; adding daily totals may exceed a combined period. JSON `accounting` names this policy and the current price-table source. `usage_runs` and `priced_runs` show how much of the token total has a dollar estimate. Live runs are absent until their history row is written, and unknown usage is different from measured zero.
 
+Completed results, registry records, and history JSON include `cost_status` (`estimated` or `unknown`) and nullable `cost_reason`: `usage_not_measured`, `model_not_observed`, `model_price_unknown`, `attempt_usage_unavailable`, or `mixed_models_without_counters`. Stats include `unpriced_reasons` counts alongside `priced_runs` and `unpriced_models`. These are list-price estimates, not billing receipts. `budget_status` is `not_requested`, `usage_not_measured`, `estimated`, `exceeded`, or `unverifiable`.
+
+New headless attempts have distinct `attempt_id` values and artifact paths, including retries on the same profile. Final payloads and registry reports expose `attempts` with their individual model evidence, counters, and estimates; top-level usage describes the final attempt, while a budget-exceeded spend includes all attempts. New isolated Codex attempts mount only a fresh sessions directory from volatile `/dev/shm` storage. The supervisor reads the exact `thread.started` rollout while it exists and at closeout, requiring matching session identity, turn timestamps within this attempt, and token counters consistent with stdout. It exports `usage_evidence` containing only the stdout attempt identity, thread id, timestamp bounds, turn ids, observed models, and normalized counters; live rollout counters can establish the first measurement before `turn.completed`. No requested model, agent-authored cost report, current profile setting, prompt, message, or tool output is used as model evidence. The raw temporary sessions are removed at closeout, including cancellation and startup failure; they are never copied into persistent run artifacts. Host profiles are not mounted. Mixed serving models stay unpriced without attributable counters. Isolated continuation without comparable launch boundaries stays unmeasured rather than charging an older conversation to the new attempt.
+
 Completed run JSON and registry reports expose `usage_model` separately from the requested `model`. Pricing uses the observed model from provider output; Codex can also supply it through the exact rollout identified by `thread.started.thread_id`. Configured defaults alone never establish serving-model identity, and missing or mixed model evidence stays unpriced. `--by model` groups Claude's `[1m]` context variant with its base model while preserving the original model string and per-run pricing. New runs record this evidence automatically. To recover missing models in existing history, run:
 
 ```bash
@@ -297,9 +302,9 @@ cdx history backfill-models --dry-run --json # Machine-readable preview
 cdx history backfill-models --apply          # Save proven models with a backup
 ```
 
-The command considers only history rows with usage and an empty or placeholder `usage_model`. Evidence is checked in order: the row's preserved JSON/JSONL stdout, a preserved run-registry report with the same run id, profile, provider and stdout path, then the exact Codex thread rollout or Claude session transcript. Thread/session ids must come from the row or its stdout, or from a preserved transcript path recorded as an exact conversation-id match. The current profile is used only to locate an exact transcript under its auth home; its configured model and latest conversation/transcript never establish a historical model. The requested `model` in a report is also ignored.
+The command considers only history rows with usage and an empty or placeholder `usage_model`. Evidence is checked in order: a supervisor-preserved isolated observation tied to the exact stdout attempt and counters, the row's preserved JSON/JSONL stdout, a preserved run-registry report with the same run id, profile, provider and stdout path, then the exact Codex thread rollout or Claude session transcript. Thread/session ids must come from the row or its stdout, or from a preserved transcript path recorded as an exact conversation-id match. The current profile is used only to locate an exact transcript under its auth home; its configured model and latest conversation/transcript never establish a historical model. The requested `model` in a report is also ignored.
 
-Only one serving model is accepted. Claude `[1m]` variants count as the same model for this check and for stats grouping; the observed spelling is preserved. Mixed models, incomplete turn models, malformed or oversized evidence, conflicting identities and missing exact transcripts stay unknown. For resumed conversations, the conservative rule is that all recorded turns in the exact transcript must agree: this command does not infer historical turn boundaries. Ambiguous higher-priority evidence stops recovery rather than being overridden by a lower-priority source. Missing files may fall through to the next source.
+Run recovery in dry-run mode first and review every evidence kind and unknown reason before applying. A missing isolated rollout with no preserved observation cannot be reconstructed from a current profile: its historical model and cost remain unknown. No historical recovery is applied automatically. Only one serving model is accepted. Claude `[1m]` variants count as the same model for this check and for stats grouping; the observed spelling is preserved. Mixed models, incomplete turn models, malformed or oversized evidence, conflicting identities and missing exact transcripts stay unknown. For resumed conversations, the conservative rule is that all recorded turns in the exact transcript must agree: this command does not infer historical turn boundaries. Ambiguous higher-priority evidence stops recovery rather than being overridden by a lower-priority source. Missing files may fall through to the next source.
 
 Text and JSON output include counts by evidence kind, counts of unknown reasons and up to 20 samples. Dry-run leaves history and run reports unchanged. `--apply` changes only missing models and their evidence annotation, preserving token counts and unrelated history bytes. It holds the history lock, saves the original bytes to a unique `state/launch_history.jsonl.models-<id>.bak` file, then atomically replaces history. The backup path is printed; a repeated apply leaves already recovered rows alone. `--apply` and `--dry-run` cannot be combined. Subsequent `cdx stats` calls price recovered models when the local price table knows them; unknown models remain unpriced.
 
@@ -459,3 +464,84 @@ It returns accepted values for `permission` (with its aliases and canonical form
 Codex ties network access to its sandbox, so any permission below `full` leaves the run unable to resolve DNS — `gh`, `curl`, and package installs fail inside an otherwise successful run. Show these warnings to whoever reads your output rather than discarding them; a run that succeeds while quietly doing less is the case they exist for.
 
 Claude result records with nonempty `permission_denials` produce a warning with code `permission_denials`, the `provider`, and the structured `permission_denials` list. Exit code 0 still means `ok: true`: a denied tool may have been replaced successfully. Empty or absent denials add no warning. With `--scrub-env on`, Claude forces its default permission mode; allow tools needed by unattended runs explicitly using `--allowedTools` via `--extra-args` (see [operations](operations.md)).
+
+### Source repository attribution and external launchers
+
+CDX captures `project` (an absolute canonical source repository path) and
+`project_source` before starting a provider or applying workspace isolation.
+Normal Git launches use the repository root, including launches from subfolders.
+Linked Git worktrees use their common Git directory's source repository, so
+normal and worktree launches share an identity even after worktree deletion.
+Unrelated repositories with the same basename retain separate full-path keys.
+Without Git evidence or an explicit source, attribution is unknown (`project:
+null`, `project_source: "unknown"` in history; `project: "-"` in project stats).
+Old cwd-only history also stays unknown: stats never inspect today's filesystem
+or profile settings to guess yesterday's project.
+
+Trusted producers such as Jarvis/remote-ops must resolve the source repository
+**before** creating a disposable mission directory, worktree, or temporary clone,
+and pass it to the installed CDX launcher:
+
+```bash
+cdx run work --cwd /temporary/mission --project /repos/remote-ops --prompt 'Fix the issue' --isolate-workspace --json
+cdx work --dir /temporary/mission --project /repos/remote-ops
+```
+
+`--project` is a trusted operator assertion, not provider output, a profile
+setting, or an environment variable. It must be an absolute normalized path,
+with symlinks already resolved by the producer; it may refer to a deleted source.
+A plain temporary clone has no reliable link to a local source repository: the
+producer must supply `--project` rather than expecting inference from a remote
+URL or directory naming convention. Existing launch-directory validation and
+execution `cwd` are unchanged. CDX records the separate identity in history,
+runtime/registry records, and launch/result JSON. Failover attempts and detached
+children retain the launch identity. `--continue-run` inherits the parent's
+recorded identity (including unknown) and rejects a different `--project`.
+Neither continuation nor backfill reattributes an older run from current profile
+configuration.
+
+Consumers should use stats `project` as the stable grouping key and
+`session_name` as the disambiguated display label. In particular, dependent
+remote-ops `scripts/cdx-stats.py` should not reduce `project` to `Path(...).name`:
+that loses disambiguation between unrelated repositories named alike. Token,
+duration, cost, and attempt counts keep the existing accounting rules; the
+existing `totals.sessions` field counts groups for the chosen grouping.
+
+### Recover historical project attribution
+
+```bash
+cdx history backfill-projects --mapping projects.json           # Preview (default)
+cdx history backfill-projects --mapping projects.json --dry-run --json
+cdx history backfill-projects --mapping projects.json --apply
+```
+
+The mapping format is deliberately generic, with exact CDX run IDs, not mission
+IDs, profile names, prefixes, or cwd values:
+
+```json
+{"version":1,"projects":[{"run_id":"exact CDX run id","project":"/repos/remote-ops"}]}
+```
+
+Operators must build this file from attributable external evidence, such as an
+exact launch receipt. CDX never imports Jarvis, scans its private state, guesses
+from disposable path prefixes, or resolves deleted worktrees. The supplied
+Tower observation (84 disposable groups attributed by receipts to remote-ops
+66, cdx-manager 10, logics-manager 6, city-jump 2) is diagnostic evidence, not a
+mapping: actual exact CDX run IDs must be obtained on Tower before repair.
+
+Without a mapping, the command can recover only from trusted project fields
+already preserved for the exact run in CDX history or its run registry. A cwd-only
+report is insufficient evidence. All attempts sharing an exact run ID must agree.
+Invalid schema, contradictory duplicate mapping entries, and unknown exact run
+IDs fail validation. An attribution conflict with known history or recorded run
+evidence blocks the entire batch, preserving the original history and returning
+exit status 1 with the conflict counts.
+
+Results report `recovered` (recoverable history rows), `unchanged`, `unresolved`,
+and `conflicting` counts, plus `applied` and `backup_path`. Counts are history
+attempts, matching existing history accounting. Dry runs write nothing. Apply
+holds the existing history lock, writes an original-byte `.projects-*.bak`
+backup, and atomically replaces history only when the complete batch has no
+conflict. Unrelated fields, usage, and malformed/unrelated history lines survive.
+Repeating the same mapping is a no-op and creates no additional backup. The
+registry and provider transcripts are never rewritten by backfill.

package/package.json

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

package/pyproject.toml

@@ -4,10 +4,10 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "cdx-manager"
-version = "0.25.1"
+version = "0.25.3"
 description = "Terminal session manager for Codex and Claude accounts."
 readme = "README.md"
-requires-python = ">=3.9"
+requires-python = ">=3.9.2"
 license = "MIT"
 authors = [
   { name = "Alexandre Agostini" }
@@ -26,11 +26,13 @@ classifiers = [
   "Topic :: Software Development",
   "Topic :: Terminals",
 ]
-dependencies = ["cryptography>=42"]
+dependencies = ["cryptography>=50.0.0"]
 
 [project.optional-dependencies]
 dev = [
-  "pytest>=8",
+  # pytest 9 requires Python 3.10; 8.4.2 is the last Python 3.9 release.
+  "pytest>=8.4.2; python_version < '3.10'",
+  "pytest>=9.0.3; python_version >= '3.10'",
   "pytest-cov>=5",
   "ruff>=0.6",
 ]
@@ -70,6 +72,7 @@ show_missing = true
 skip_empty = true
 
 [tool.ruff]
+extend-exclude = [".jarvis-input"]
 target-version = "py39"
 line-length = 140
 

package/src/cli.py

@@ -245,7 +245,7 @@ def _print_help(use_color=False):
         f"  {_style('cdx reset <name> [--yes] [--json]', '36', use_color)}",
         f"  {_style('cdx auth refresh <name|all> [--json]', '36', use_color)}",
         f"  {_style('cdx select --provider PROVIDER [--min-reasoning-effort minimal|low|medium|high|xhigh] [--min-power minimal|low|medium|high|xhigh] [--require-ready] [--refresh] --json', '36', use_color)}",
-        f"  {_style('cdx run [session] --cwd PATH (--prompt-file PATH|--prompt TEXT|--prompt-file -) [--provider PROVIDER] [--model MODEL] [--kind assistant|code-review|retro] [--reasoning-effort minimal|low|medium|high|xhigh] [--power minimal|low|medium|high|xhigh] [--permission review|default|auto|full|workspace-write|read-only|danger-full-access] [--timeout-seconds N] [--label TEXT] [--max-parallel N] [--continue-run RUN_ID] [--detach] [--failover] [--refresh] --json', '36', use_color)}",
+        f"  {_style('cdx run [session] [--remote SSH_TARGET] --cwd 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] [--timeout-seconds N] [--label TEXT] [--max-parallel N] [--continue-run RUN_ID] [--detach] [--failover] [--refresh] --json', '36', use_color)}",
         f"  {_style('cdx runs [--limit N] [--since 7d|today|DATE] [--running] --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)}",
@@ -260,10 +260,11 @@ def _print_help(use_color=False):
         f"  {_style('cdx power|perm|fast|model <name|all|provider:PROVIDER|a,b> <value|default> [--json]', '36', use_color)}",
         f"  {_style(SET_USAGE[len('Usage: '):], '36', use_color)}",
         f"  {_style('cdx unset <name>|--sessions all|a,b|--provider PROVIDER (--power|--permission|--fast|--rtk|--logics|--notify|--notify-preview|--model|--priority|--all) [--json]', '36', use_color)}",
+        f"  {_style('cdx history backfill-projects [--mapping FILE] [--dry-run|--apply] [--json]', '36', use_color)}",
         f"  {_style('cdx history [name] [--limit N] [--summary] [--since 7d|today|DATE] [--from DATE] [--to DATE] [--json]', '36', use_color)}",
         f"  {_style('cdx stats [name] [--since 7d|today|DATE] [--from DATE] [--to DATE] [--by session|project|model] [--json]', '36', use_color)}",
         f"  {_style('cdx last [--json]', '36', use_color)}",
-        f"  {_style('cdx resume <name> [--conversation <id>] [--json]', '36', use_color)}",
+        f"  {_style('cdx resume <name> [--project PATH] [--conversation <id>] [--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)}",
@@ -295,7 +296,7 @@ def _print_help(use_color=False):
         _style("Notifications:", "1", use_color),
         f"  {_style('cdx set <name> --notify on', '36', use_color)}  # agent finishes or needs attention",
         f"  {_style('cdx ready', '36', use_color)}  # next session to become ready",
-        f"  {_style('cdx <name> [--on-busy fail|ask] [--json]', '36', use_color)}",
+        f"  {_style('cdx <name> [--project PATH] [--on-busy fail|ask] [--json]', '36', use_color)}",
         "    --on-busy: fail immediately if already running; ask (default) prompts only with a terminal and without --json",
         f"  {_style('cdx <name> --prompt TEXT|--prompt-file PATH', '36', use_color)}  # start with a first message",
         f"  {_style('cdx <name> --dir PATH --task TEXT --end-state TEXT', '36', use_color)}  # start on a task, with what the go-ahead covers",
@@ -637,7 +638,8 @@ def main(argv, options=None):
     if handler:
         return handler(rest, ctx)
 
-    from .commands.launch import _parse_launch_args, _read_launch_prompt
+    from .commands.launch import _parse_launch_args, _pop_value_flag, _read_launch_prompt
+    project_path, rest = _pop_value_flag(rest, "--project", "Usage: cdx <name> [--project PATH]")
     directory, launch_args, prompt, on_busy = _parse_launch_args(rest)
     if all(arg in ("--json", "-r", "--resume") for arg in launch_args):
         resume = "-r" in launch_args or "--resume" in launch_args
@@ -648,7 +650,7 @@ def main(argv, options=None):
         if has_prompt and (ctx["service"]["get_session"](command) or {}).get("provider") == PROVIDER_OLLAMA:
             raise CdxError("cdx <name>: --prompt and --prompt-file are not supported for Ollama sessions.")
         return handle_launch(command, ctx, initial_prompt=_read_launch_prompt(prompt), resume=resume,
-                             directory=directory, on_busy=on_busy)
+                             directory=directory, on_busy=on_busy, project_path=project_path)
 
     raise CdxError(f"Unknown command: {command}. Use cdx --help.")
 

package/src/cli_args.py

@@ -43,12 +43,12 @@ HISTORY_USAGE = "Usage: cdx history [name] [--limit N] [--summary] [--since 7d|t
 STATS_USAGE = "Usage: cdx stats [name] [--since 7d|today|DATE] [--from DATE] [--to DATE] [--by session|project|model] [--json]"
 STATS_GROUPS = ("session", "project", "model")
 LAST_USAGE = "Usage: cdx last [--json]"
-RESUME_USAGE = "Usage: cdx resume <name> [--conversation <id>] [--on-busy fail|ask] [--json]"
+RESUME_USAGE = "Usage: cdx resume <name> [--project PATH] [--conversation <id>] [--on-busy fail|ask] [--json]"
 CAN_RESUME_USAGE = "Usage: cdx can-resume <name> [--conversation <id>] [--json]"
 SESSIONS_USAGE = "Usage: cdx sessions [--all] --json"
 SELECT_USAGE = "Usage: cdx select --provider PROVIDER [--min-reasoning-effort minimal|low|medium|high|xhigh] [--min-power minimal|low|medium|high|xhigh] [--require-ready] [--refresh] --json"
 NEXT_USAGE = "Usage: cdx next [--json] [--refresh]"
-RUN_USAGE = "Usage: cdx run [session] (--cwd|--dir) PATH (--prompt-file PATH|--prompt TEXT|--prompt-file -) [--provider PROVIDER] [--model MODEL] [--kind assistant|code-review|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] [--label TEXT] [--max-parallel N] [--continue-run RUN_ID] [--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."
@@ -546,12 +546,20 @@ def cdx_schema():
             "run": [
                 "invalid_cwd",
                 "session_disabled",
+                "session_busy",
+                "auth_lock_failed",
+                "remote_unavailable",
+                "remote_version_mismatch",
+                "remote_provider_unsupported",
+                "remote_credential_expired",
+                "remote_isolation_unavailable",
                 "no_suitable_session",
                 "provider_cli_not_found",
                 "provider_start_failed",
                 "provider_failed",
                 "provider_timeout",
                 "budget_exceeded",
+                "budget_unverifiable",
                 "run_cancelled",
                 "too_many_runs",
                 "failover_exhausted",
@@ -672,6 +680,9 @@ def _parse_max_parallel(value):
 
 def _parse_run_args(args):
     parsed = _parse_run_flag_args(args, {
+        "--remote": {"key": "remote", "type": "str", "default": None},
+        "--remote-prefix": {"key": "remote_prefix", "type": "str", "default": None},
+        "--project": {"key": "project", "type": "str", "default": None},
         "--cwd": {"key": "cwd", "type": "str", "default": None},
         "--dir": {"key": "cwd", "type": "str", "default": None},
         "--prompt-file": {"key": "prompt_file", "type": "str", "default": None},
@@ -730,11 +741,20 @@ def _parse_run_args(args):
     if parsed["continue_run"] is not None and not parsed["continue_run"].strip():
         raise CdxArgumentError("cdx run: --continue-run requires a nonempty run id.",
                                code=ARG_CODE_INVALID_VALUE, arguments=["--continue-run"])
+    if parsed["remote"] is not None and not parsed["remote"].strip():
+        raise CdxArgumentError("cdx run: --remote requires a nonempty SSH target.",
+                               code=ARG_CODE_INVALID_VALUE, arguments=["--remote"])
+    if parsed["remote_prefix"] is not None and (not parsed["remote"] or not parsed["remote_prefix"].strip()):
+        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"])
     return {
         "name": name,
+        "remote": parsed["remote"],
+        "remote_prefix": parsed["remote_prefix"],
         "provider": parsed["provider"],
         "cwd": parsed["cwd"],
+        "project": parsed["project"],
         "prompt_file": parsed["prompt_file"],
         "prompt": parsed["prompt"],
         "continue_run": parsed["continue_run"],

package/src/codex_usage.py

@@ -18,7 +18,7 @@ CODEX_AUTH_LOCK_NAME = ".cdx-auth.lock"
 
 
 @contextlib.contextmanager
-def codex_auth_lock(auth_home, blocking=False, timeout_seconds=None, retry_interval_seconds=0.05):
+def codex_auth_lock(auth_home, blocking=False, timeout_seconds=None, retry_interval_seconds=0.05, strict=False):
     """Serialize codex token refreshes per CODEX_HOME.
 
     Codex rotates its OAuth refresh_token on refresh and invalidates the old
@@ -28,6 +28,8 @@ def codex_auth_lock(auth_home, blocking=False, timeout_seconds=None, retry_inter
     the lock is held, False when a non-blocking acquire found it already taken.
     ponytail: POSIX flock only; on Windows (no fcntl) this is a no-op.
     """
+    if strict and (not auth_home or fcntl is None):
+        raise OSError("A POSIX authentication lock is required")
     if not auth_home or fcntl is None:
         yield True
         return
@@ -35,6 +37,8 @@ def codex_auth_lock(auth_home, blocking=False, timeout_seconds=None, retry_inter
         os.makedirs(auth_home, exist_ok=True)
         handle = open(os.path.join(auth_home, CODEX_AUTH_LOCK_NAME), "w")
     except OSError:
+        if strict:
+            raise
         yield True
         return
     deadline = None if timeout_seconds is None else time.monotonic() + timeout_seconds