Skip to content

fix(codex): admit Codex CLI 0.163.0 or later for native registration - #3529

Merged
Daniel Meppiel (danielmeppiel) merged 3 commits into
mainfrom
danielmeppiel-fix-3378-codex-floor
Nov 11, 2026
Merged

Daniel Meppiel (danielmeppiel) merged 3 commits into
mainfrom
danielmeppiel-fix-3378-codex-floor

Conversation

@danielmeppiel

@danielmeppiel Daniel Meppiel (danielmeppiel) commented Nov 10, 2026 •

Copy link
Copy Markdown
Collaborator

Description

TL;DR — apm 0.35.0 admitted native Codex compatibility-bundle registration only when codex --version printed exactly codex-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_scope compared stdout.strip() != "codex-cli 0.163.0"; Codex 0.164.0 (current) was refused for every install of a .codex-plugin/plugin.json bundle.
  • Codex self-updates, so each Codex release would break the route again until APM re-qualified the exact string.
  • The refusal message said "qualified only for 0.163.0", giving users no actionable minimum.

Approach (WHAT)

Before After
exact string codex-cli 0.163.0 parse codex-cli X.Y.Z[-pre], admit core ≥ 0.163.0
0.163.0 prereleases refused still refused (semver: prerelease precedes release)
unparseable output refused still refused, message names 0.163.0 or later
app-server protocol checks unchanged — malformed responses fail before any write
integration marker version= exact min_version= stable release at or above floor

Implementation (HOW)

File Change
src/apm_cli/codex_plugins/client.py QUALIFIED_CODEX_VERSION → MINIMUM_CODEX_VERSION; new is_qualified_codex_version(); refusal messages name the minimum. Scope gate and CodexRpc untouched.
scripts/architecture_linter/checks/marketplace_package_and_registration.py Required-anchor string follows the renamed constant.
tests/integration/conftest.py, test_codex_native_plugin_lifecycle.py Marker kwarg min_version with numeric comparison.
tests/unit/test_codex_native_client.py Admit/refuse matrix, real POSIX stand-in codex binaries for the version gate and for malformed app-server responses.
tests/unit/test_codex_native_registrar.py Malformed app-server on admitted 0.164.0 → only initialize sent, no .codex-native/ ledger or snapshot written.
Docs + apm-usage guidance + CHANGELOG "exactly 0.163.0" → "0.163.0 or later"; marker docs.

Admission 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"]
Loading

Trade-offs

  • Open-ended floor vs tested range. An upper bound would recreate the self-update breakage. Protocol drift in a future Codex is instead caught by the existing strict app-server response checks, which this PR covers with new tests.
  • Prereleases above the floor (e.g. 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.
  • Out of scope per the record: non-codex targets, project scope, loose projection, [BUG] Cached Codex plugin installation fails with an invalid source-pin error #3388, hooks/agents.

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

  • Bug fix
  • New feature
  • Documentation
  • Maintenance / refactor

Testing

  • Tested locally
  • All existing tests pass (targeted; see note on pre-existing lifecycle failures)
  • Added tests for new functionality (if applicable)

Validation

Command Result
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 -q 125 passed
uv run --extra dev pytest tests/integration/test_architecture_owner_rule_mutations.py -q -k codex 19 passed
ruff check / ruff format --check (src, tests, architecture linter) clean
pylint --enable=R0801 --min-similarity-lines=10 --fail-on=R0801 ... 10.00/10
bash scripts/lint-auth-signals.sh clean
python scripts/lint_architecture_boundaries.py --root . exit 0
Mutation-break: new tests vs HEAD client 22 failed (as expected)
Mutation-break: admit floor prerelease (core >= minimum) 2 failed (as expected)

Scenario evidence

User-promise scenario Proof Principle
Current Codex (0.164.0) installs a compatibility bundle test_native_client_admits_minimum_and_later_versions, test_stand_in_binary_version_gate, native transcript below Native-first consumption
Older/unrecognized Codex refused with actionable minimum test_native_client_refuses_older_or_unparseable_versions, test_missing_native_client_names_minimum Fail-closed, honest diagnostics
Protocol drift never writes native state test_admitted_client_fails_closed_on_malformed_app_server, test_malformed_app_server_on_newer_client_fails_closed_without_writes Secure by default
Project scope still refused before probing existing test_project_scope_refusal_does_not_probe_or_write Scope isolation
Native-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>:

  • install → exit 0; Reconciled 1 Codex native plugin registration(s) at user scope; config.toml gains [plugins."probe@apm-…"] enabled = false and an APM-owned marketplace; ownership ledger records the plugin.
  • restore (apm_modules deleted, apm install -g -t codex) → exit 0; native config unchanged.
  • update (skill body changed, reinstall) → exit 0; reconciled; Codex plugin cache now contains Body v2.
  • uninstall (apm uninstall -g <pkg>) → exit 0; config.toml emptied of APM entries; ledger {"plugins": {}}.
  • With an unrunnable codex on PATH, install fails with "requires Codex CLI 0.163.0 or later" and writes nothing.

Note

tests/integration/test_codex_native_plugin_lifecycle.py has 4 failures (apm audit --ci drift on _local source files; a loose MCP name conflict) that reproduce identically on main with 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

Spec conformance (OpenAPM v0.1)

  • Spec edit
  • Manifest edit
  • Test edit
  • CONFORMANCE.{md,json} regenerated
  • N/A -- this PR does not change OpenAPM-observable behaviour.

Co-authored-by: Copilot 223556219+Copilot@users.noreply.github.com

Copilot AI balanced review requested due to automatic review settings 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>

Copilot AI left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

🟡 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

Comment thread src/apm_cli/codex_plugins/client.py Resolved
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>
@danielmeppiel
Daniel Meppiel (danielmeppiel) force-pushed the danielmeppiel-fix-3378-codex-floor branch from a1526b6 to 258a6fb Compare November 10, 2026 18:25
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>
@danielmeppiel
Daniel Meppiel (danielmeppiel) force-pushed the danielmeppiel-fix-3378-codex-floor branch from 258a6fb to 4e84fab Compare November 10, 2026 18:39
@danielmeppiel
Daniel Meppiel (danielmeppiel) merged commit d161eee into main Nov 11, 2026
27 checks passed
@danielmeppiel
Daniel Meppiel (danielmeppiel) deleted the danielmeppiel-fix-3378-codex-floor branch November 11, 2026 12:11
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

2 participants