Repository navigation
fix(codex): admit Codex CLI 0.163.0 or later for native registration - #3529
Merged
Daniel Meppiel (danielmeppiel) merged 3 commits intoNov 11, 2026
Merged
Conversation
Daniel Meppiel (danielmeppiel)
requested a review
from Sergio Sisternes (sergio-sisternes-epam)
as a code owner
November 10, 2026 17:05
Daniel Meppiel (danielmeppiel)
added a commit
that referenced
this pull request
Nov 10, 2026
Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com>
Contributor
There was a problem hiding this comment.
🟡 Changes recommended
The version gate accepts malformed prerelease versions, allowing registration to proceed instead of refusing unrecognized versions.
1 open issue
What changed in this PR
This PR addresses #3378’s exact-version restriction by allowing Codex CLI 0.163.0 or later for native compatibility-bundle registration. User-scope restrictions and app-server protocol checks remain unchanged.
Changes:
- Replace exact-version matching with minimum-version parsing and actionable refusal messages.
- Add admission, rejection, and malformed-protocol regression tests; update integration gating to a stable minimum version.
- Align documentation, usage guidance, and the architecture guard with the new requirement.
| File | Description |
|---|---|
tests/unit/test_codex_native_registrar.py |
Verify malformed initialization causes no native state writes. |
tests/unit/test_codex_native_client.py |
Expand version-gate and protocol-failure coverage. |
tests/integration/test_codex_native_plugin_lifecycle.py |
Require a minimum Codex version rather than an exact version. |
tests/integration/conftest.py |
Implement stable minimum-version prerequisite checks. |
src/apm_cli/codex_plugins/client.py |
Parse versions and enforce the minimum with updated diagnostics. |
scripts/architecture_linter/checks/marketplace_package_and_registration.py |
Update the required version-constant anchor. |
packages/apm-guide/.apm/skills/apm-usage/package-authoring.md |
State the minimum version for compatibility bundles. |
packages/apm-guide/.apm/skills/apm-usage/commands.md |
Update install requirements and refusal conditions. |
docs/src/content/docs/reference/package-types.md |
Document minimum-version native registration. |
docs/src/content/docs/contributing/integration-testing.md |
Document the min_version marker option. |
docs/src/content/docs/consumer/installing-from-marketplaces.md |
Clarify minimum requirements and measured qualification. |
CHANGELOG.md |
Record restored compatibility with newer Codex releases. |
Review effort: Balanced
Daniel Meppiel (danielmeppiel)
added a commit
that referenced
this pull request
Nov 10, 2026
Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com>
Daniel Meppiel (danielmeppiel)
force-pushed
the
danielmeppiel-fix-3378-codex-floor
branch
from
November 10, 2026 18:25
a1526b6 to
258a6fb
Compare
Replace the exact 0.163.0 version gate with a semver-aware minimum so self-updating Codex installs (0.164.0+) are admitted. Older, floor prerelease, and unrecognized versions are refused with the minimum named; app-server protocol checks still fail closed before any write. Refs #3378 Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com>
Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com>
Address review: empty/dotted prerelease identifiers and leading zeros in numeric identifiers are unrecognized versions and are now refused. Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com>
Daniel Meppiel (danielmeppiel)
force-pushed
the
danielmeppiel-fix-3378-codex-floor
branch
from
November 10, 2026 18:39
258a6fb to
4e84fab
Compare
Daniel Meppiel (danielmeppiel)
deleted the
danielmeppiel-fix-3378-codex-floor
branch
November 11, 2026 12:11
This was referenced Nov 11, 2026
Merged
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.

Description
TL;DR — apm 0.35.0 admitted native Codex compatibility-bundle registration only when
codex --versionprinted exactlycodex-cli 0.163.0, so every self-updated Codex (0.164.0+) was refused. This PR replaces that exact match with a semver-aware minimum of 0.163.0, keeps the fail-closed app-server protocol checks, and updates docs and guidance to state the minimum.Problem (WHY)
CodexNativeClient.for_scopecomparedstdout.strip() != "codex-cli 0.163.0"; Codex 0.164.0 (current) was refused for every install of a.codex-plugin/plugin.jsonbundle.Approach (WHAT)
codex-cli 0.163.0codex-cli X.Y.Z[-pre], admit core ≥ 0.163.00.163.0 or laterversion=exactmin_version=stable release at or above floorImplementation (HOW)
src/apm_cli/codex_plugins/client.pyQUALIFIED_CODEX_VERSION→MINIMUM_CODEX_VERSION; newis_qualified_codex_version(); refusal messages name the minimum. Scope gate andCodexRpcuntouched.scripts/architecture_linter/checks/marketplace_package_and_registration.pytests/integration/conftest.py,test_codex_native_plugin_lifecycle.pymin_versionwith numeric comparison.tests/unit/test_codex_native_client.pycodexbinaries for the version gate and for malformed app-server responses.tests/unit/test_codex_native_registrar.pyinitializesent, no.codex-native/ledger or snapshot written.apm-usageguidance + CHANGELOGAdmission flow (legend: boxes are gate stages; every refusal path ends before any native write):
flowchart LR A["codex --version"] --> B{"codex-cli X.Y.Z[-pre]?"} B -->|"unparseable or nonzero exit"| R["refuse: names 0.163.0 or later"] B -->|"core below floor or 0.163.0 prerelease"| R B -->|"core at or above 0.163.0"| C["app-server initialize"] C -->|"malformed response"| F["fail closed, no native write"] C -->|"valid"| W["user-scope registration"]Trade-offs
0.164.0-alpha) are admitted at runtime (semver-greater than 0.163.0) but the integration marker requires a stable release, so CI qualification evidence comes only from stable builds.Issue and approved scope
Issue: #3378
Human scope-approval comment: #3378 (comment)
Fixes #3378 — delivers every Done-when item (stand-in tests for 0.163.0/0.164.0 admission and older/unparseable refusal, malformed app-server fail-closed without writes, native 0.164.0 evidence below, docs/guidance/marker updated).
Type of change
Testing
Validation
uv run --extra dev pytest tests/unit/test_codex_native_client.py tests/unit/test_codex_native_registrar.py tests/unit/test_codex_native_admission.py tests/unit/test_codex_native_snapshot.py tests/unit/install/test_pipeline_preflight.py tests/unit/commands/test_uninstall_atomic_selection.py tests/spec_conformance/test_codex_compatibility_admission_reqs.py -quv run --extra dev pytest tests/integration/test_architecture_owner_rule_mutations.py -q -k codexruff check/ruff format --check(src, tests, architecture linter)pylint --enable=R0801 --min-similarity-lines=10 --fail-on=R0801 ...bash scripts/lint-auth-signals.shpython scripts/lint_architecture_boundaries.py --root .HEADclientcore >= minimum)Scenario evidence
test_native_client_admits_minimum_and_later_versions,test_stand_in_binary_version_gate, native transcript belowtest_native_client_refuses_older_or_unparseable_versions,test_missing_native_client_names_minimumtest_admitted_client_fails_closed_on_malformed_app_server,test_malformed_app_server_on_newer_client_fails_closed_without_writestest_project_scope_refusal_does_not_probe_or_writeNative-client evidence: real Codex CLI 0.164.0, user scope, macOS arm64 (scratch HOME)
Probe plugin with
.codex-plugin/plugin.json+ one skill,apm install -g -t codex <pkg>:Reconciled 1 Codex native plugin registration(s) at user scope;config.tomlgains[plugins."probe@apm-…"] enabled = falseand an APM-owned marketplace; ownership ledger records the plugin.apm_modulesdeleted,apm install -g -t codex) → exit 0; native config unchanged.Body v2.apm uninstall -g <pkg>) → exit 0;config.tomlemptied of APM entries; ledger{"plugins": {}}.codexon PATH, install fails with "requires Codex CLI 0.163.0 or later" and writes nothing.Note
tests/integration/test_codex_native_plugin_lifecycle.pyhas 4 failures (apm audit --cidrift on_localsource files; alooseMCP name conflict) that reproduce identically onmainwith real Codex 0.163.0, so they are pre-existing and independent of the version gate. The other 2 lifecycle tests pass on 0.164.0.How to test
npm i --prefix /tmp/cx @openai/codex@0.164.0and put/tmp/cx/node_modules/.binfirst onPATH.-t codex: install now succeeds; plugin registered disabled.codexprintingcodex-cli 0.162.1: install refused, message names0.163.0 or later.uv run --extra dev pytest tests/unit/test_codex_native_client.py -q.Spec conformance (OpenAPM v0.1)
CONFORMANCE.{md,json}regeneratedCo-authored-by: Copilot 223556219+Copilot@users.noreply.github.com