Feature: provenance-aware Codex CLI update manager

Start with the existing contracts referenced by #356, #2519, #2382, and #2632, then inspect the entry points represented by ocx system codex-cli-update check, dry-run, apply, and status. Use the listed acceptance scenarios to define coverage for provenance, process blockers, deterministic plans, stale-plan rejection, and post-install readback; done requires the focused provenance, apply, dashboard, and documentation changes.

Area

Multiple areas

What are you trying to accomplish?

OpenCodex already detects the Codex runtime it uses, restores an established shim after a supported external update, and can identify long-lived app-server processes. It does not yet provide one safe workflow for checking and updating the independently installed Codex CLI that OpenCodex is actually integrating with.

The desired workflow is an explicit, provenance-aware Codex CLI update manager. It should tell the operator which selected CLI installation is manageable, which installation channel owns it, whether an update can proceed without disrupting an active Codex session, and what exact version would be installed before any mutation occurs.

What prevents this today?

Codex can coexist in several independent forms on one host: an npm global installation, a native app bundle, a standalone installer, or a version-manager-owned tree. A path and codex --version result are not enough to decide which installer owns that runtime or whether OpenCodex may safely replace it.

Operators currently have to combine separate manual steps:

1. determine which codex runtime OpenCodex selected;
2. infer how that runtime was installed;
3. check whether an interactive CLI, app-server, or code-mode host still uses it;
4. run the matching installer;
5. restore and verify the OpenCodex shim when applicable; and
6. read the actual runtime back instead of trusting an installer exit code.

This is error-prone when an app-bundled CLI and an independently installed CLI coexist. It is also unsafe to generalize the existing OpenCodex self-update worker to Codex: the two packages have different ownership, process, and rollback boundaries.

What should OpenCodex do?

Provide a separate, explicitly invoked Codex CLI update workflow with these phases:

1. Inspect and dry-run

   • Resolve the exact selected Codex runtime.
   • Classify its installation provenance from direct package or installer evidence.
   • Report current version, update channel, redacted canonical location, shim state, and active or unknown process blockers.
   • Produce a deterministic plan without writing files, changing configuration, or starting an installer.

2. Explicit apply

   • Require an operator-confirmed plan ID.
   • Revalidate runtime identity, installation provenance, current version and hash, target version and integrity, and process blockers immediately before applying.
   • Install one exact resolved version through the verified owner channel.
   • Read back the selected runtime and restore the existing shim only when that installation had an eligible shim before the update.
   • Classify the result from readback as applied, not applied, ambiguous, or applied with shim repair still required.

3. Dashboard integration

   • Present Codex CLI updates separately from OpenCodex updates.
   • Keep Apply disabled until the operator has reviewed the dry-run plan and confirmed that only the selected independent CLI will be changed.

Safety requirements:

• Native app, Store/MSIX, and app-bundled Codex binaries are always non-managed.
• Version-manager-owned and otherwise unverified installations are non-managed; OpenCodex must not adopt or rewrite them.
• An active matching Codex session defers the update. Unknown process identity or failed enumeration also defers it.
• OpenCodex must not terminate or restart Codex, the native app, app-server, code-mode host, proxy, or tray as part of this workflow.
• latest is resolved before apply and the exact version plus registry integrity or installer digest is bound into the plan.
• A stale plan is rejected rather than silently regenerated.
• Ambiguous post-install state is not retried or rolled back automatically.
• No app-bundle copying or manual restoration of a package tree is used as rollback.

The implementation should remain reviewable as three focused changes: provenance and dry-run; apply engine and CLI/management API; dashboard and documentation.

Example usage or interface

ocx system codex-cli-update check --json
ocx system codex-cli-update dry-run --channel latest --json
ocx system codex-cli-update apply --plan-id <id> --yes --json
ocx system codex-cli-update status <job-id> --json

Example non-managed result:

{
  "selectedVersion": "0.149.0",
  "provenance": "app-bundle",
  "managed": false,
  "reason": "app_bundle",
  "installerCommand": null
}

Example deferred result:

{
  "managed": true,
  "status": "deferred",
  "reason": "active_codex_session",
  "installerStarted": false
}

Alternatives or workarounds

• Running the installation command manually and then ocx ensure works when the operator already knows the owning channel and no Codex process is using that installation. It does not provide a bound plan or post-readback classification.
• A scheduler or cross-host updater would add a second orchestration problem before the single-host operation is safe. This proposal deliberately leaves scheduling and multi-host coordination out of scope.
• Updating the native desktop app remains the app platform's responsibility.

Additional context

This proposal builds on, rather than duplicates, existing contracts:

• #356 restores an established OpenCodex shim after a supported external npm update.
• #2519 refuses to adopt version-manager-owned Codex installations and provides actionable diagnostics.
• #2382 keeps desktop-app restart an explicit opt-in operation.
• #2632 fails closed when the OpenCodex package tree changes under a live process.

Acceptance tests should cover npm shim-to-backing provenance, simultaneous PATH candidates, app bundles, version-manager layouts, unverified standalone installs, active and unknown process identity, PID reuse, a dry run with zero writes and zero installer spawns, deterministic plan identity, stale-plan rejection, and post-install readback taking precedence over exit status.

Checks

• I searched existing issues and documentation.
• This request describes a concrete OpenCodex workflow rather than merely naming a desired technology.
• I removed secrets and personal data.