fix: keep Codex MCP identity outside native settings

[sama Pyb (Pybsama)]

Description

APM writes an id setting into Codex MCP server entries, but Codex's native schema rejects that field. Stop emitting it for stdio and HTTP servers, and retain registry UUID matching in an escaped TOML comment. Conflict detection and installed-server lookup read that metadata, including legacy IDs, without treating it as proof of ownership.

On MCP regeneration, remove legacy IDs only from entries recorded as APM-owned. Preserve the existing narrow adoption rule for legacy self-defined entries that exactly match the saved baseline; a nonempty UUID disqualifies that adoption. Unrelated user entries and settings stay outside migration. Inline MCP containers being written and owned inline entries being repaired may expand into regular tables, retaining their values and comments. Reparse the serialized TOML before atomically writing it. The consumer documentation explains regeneration and ownership limits.

Issue and approved scope

Fixes #3087.

Human scope approval: #3087 (comment)

This completes the bounded Codex adapter repair. It adds no shared MCP schema, target, credential model, or trust policy.

Type of change

• Bug fix
• Documentation

Testing

• Tested locally
• Added regression tests

Regression tests cover both transports, save/reparse UUID alias matching, owned migration, unowned and edited-entry preservation, and legacy baseline adoption. Hermetic project- and user-scope CLI tests verify regeneration and convergence.

Generated stdio and HTTP configurations were validated against the official Codex schema and the installed Codex CLI 0.159.0-alpha.12.1 in strict mode. MCP entries were disabled during initialization, so no MCP server was launched. This validates that client version, not all Codex releases.

Final focused adapter/conflict/ownership/integrator/lifecycle suite: 569 passed. The schema/ownership/lifecycle subset also passes with the declared minimum tomlkit==0.13.0: 74 passed.

Eight final runtime fixtures pass official-schema validation and strict Codex initialization with exit code 0 and empty stderr: two fresh transport configurations in an empty inline MCP container, plus legacy stdio/HTTP entries in standard, out-of-order, inline-child, nested-inline-parent, dotted-container, and dotted-root layouts. Regression tests also cover deleting a legacy ID at the beginning, middle, or end of an inline table.

Full-source Ruff lint/format and pylint duplication checks, architecture/auth boundaries, YAML I/O/file-length/portable-path guards, and assertion/duplicate-test quality checks pass. The full functional suite, Windows runtime, and other Codex versions were not tested locally.

Spec conformance (OpenAPM v0.1)

No normative requirement changes. This repairs output for an existing client adapter while preserving APM's ownership and conflict safeguards; it introduces no new manifest, lockfile, or native configuration setting.

[Copilot]

Copilot review overview

🟡 Changes recommended

The changelog entry does not use the required pull-request-number suffix.

Review effort: Balanced
Findings: 1

Open (1)

• Changelog entry uses issue reference instead of PR number · New

What changed in this PR

Removes unsupported Codex MCP id settings while preserving registry identity and ownership-safe migration.

Changes:

• Stores registry IDs in escaped TOML comments.
• Migrates only APM-owned legacy entries.
• Adds lifecycle coverage and consumer guidance.

File	Description
src/​apm_cli/​adapters/​client/​codex.py	Implements comment metadata and migration.
src/​apm_cli/​core/​conflict_detector.py	Reads Codex registry metadata.
src/​apm_cli/​install/​mcp/​ownership.py	Preserves conservative legacy adoption.
src/​apm_cli/​integration/​mcp_integrator_install.py	Runs owned-entry migration.
src/​apm_cli/​registry/​operations.py	Detects installed Codex UUIDs.
tests/​unit/​test_codex_mcp_native_schema.py	Covers schema and migration behavior.
tests/​unit/​test_codex_adapter_phase3.py	Updates native-setting expectations.
tests/​unit/​test_codex_adapter_compatibility.py	Updates compatibility expectations.
tests/​integration/​test_codex_mcp_schema_lifecycle.py	Tests CLI regeneration and convergence.
docs/​src/​content/​docs/​consumer/​install-mcp-servers.md	Documents metadata and migration limits.
CHANGELOG.md	Records the fix.

---

💡 Add a code-review agent skill or configure MCP servers for context-aware, tailored reviews. Learn more in the docs.

[Daniel Meppiel (danielmeppiel)]

APM Review Panel: ship_now

Codex MCP output follows the native schema while preserving APM identity, ownership and user settings. All six technical workflows now pass on the published head.

panel-mode=delta; retained-personas=test-coverage-expert,apm-ceo; current-pass=faithful-carry-forward

cc sama Pyb (@Pybsama) Sergio Sisternes (@sergio-sisternes-epam) -- the existing advisory is refreshed with completed execution evidence.

The genuine seven-specialist delta had no findings. The subsequent narrow test-coverage review and CEO synthesis retained ship_now on 570b1c4; no broad panel was repeated here. All five Codex production files and core regression files remain byte-identical. Faithful main merges resolved only CHANGELOG conflicts, retaining both histories and the intervening Copilot, marketplace, Claude and local-provenance safeguards. Codex documentation additions are unchanged; incoming documentation changes are preserved.

Recommendation

Retain ship_now for 07a3e30745e762f59c4eafc1715e5e7d856eeec2. This is technical readiness, not human approval or platform admission. Existing requested reviewers Daniel Meppiel (@danielmeppiel) and Sergio Sisternes (@sergio-sisternes-epam) are unchanged. The worker never merges.

The format-correct scope record preserves all six original fields. The original official-schema condition remains satisfied: RawMcpServerConfig excludes id. Registry identity stays in comments, never becomes ownership authorization, and only recorded APM-managed entries are repaired.

Folded in this run

• Repair-count feedback and project/user fresh-repair-no-op assertions; practical regeneration documentation, user-owned fallback and identity-comment example; guide placement, changelog consolidation and decoder reuse (365349b0).
• Native-ID assertions and main's runtime-header/ownership safeguards (a1fc2349, 570b1c4).
• Four real frozen-admission conformance cases and stale expectation repairs, without a waiver or new requirement (7ae1ef3).
• Faithful current-main integration with both CHANGELOG histories (86b23070, 07a3e307).

Copilot signals reviewed

The changelog suffix finding was legitimate, fixed as (#3157) in 395d4955, and its existing thread is resolved.

Deferred (out-of-scope follow-ups)

A polymorphic base-adapter registry identity API remains a separate cross-target refactor. The approved Codex-only scope excludes shared-translator and other-target expansion.

Verified execution

• Tested head: 07a3e307; incorporated/tested main: bd672981.
• Focused functional suite: 394 passed, 2 skipped, 18 subtests passed. Both opt-in skipped provenance cases were then explicitly executed: 2 passed.
• 14 official-schema and actual Codex CLI 0.157.1 fixtures passed; the unsupported-ID negative control was rejected.
• Version-2 canonical-owner evidence passed schema and semantic verification for both detected owners, with three executed functional nodes checked against JUnit.
• Seven independent exact-head mutations produced 102 expected assertion failures: native ID 12, repair feedback 2, ownership exclusion 4, comment identity 36, TOML reparse 2, managed migration 42, canonical frozen admission 4. Every guard was restored; the subsequent suite passed 147 tests, and the tracked diff is clean.
• All seven current lint gates passed, including the expanded Ruff/pylint script scope and Windows probe helper. Auth and architecture boundaries passed. Conformance: 129 requirements aligned, generated artifacts unchanged; assertion and duplicate-test ratchets passed.

CI

All six existing pull_request workflows actually executed on 07a3e307: 18 jobs succeeded; the Docs deployment job was intentionally skipped.

Workflow	Result
CI	success
CodeQL	success
Docs	success
Merge admission check	success
NOTICE Drift	success
Spec conformance	success

Uploaded CodeQL analyses 1966054287 (Python) and 1966050912 (Actions) have zero results and match observed synthetic merge 6bb96c10, whose parents are bd672981 and 07a3e307.

Current compatibility and admission

A separate strict merge preview against newer main 6333b56a succeeds; all 14 incoming-only paths preserve main's exact blobs. This preview is not a claim that the functional suite or CI tested that newer main. GitHub reports MERGEABLE. The live account has admin=false, maintain=false, push=true; platform admission remains the parent's independent responsibility. No permission workaround or empty push was attempted.

Convergence

Counters retained: 3 outer iterations, 2 Copilot rounds, 1 CI-recovery iteration. No additional broad panel or review request.

Retained narrow panel findings

Test-coverage-expert: no findings. The test-only recovery strengthens native-ID assertions and adds four genuine frozen conformance cases without weakening safeguards. The CEO retained ship_now; the preceding seven-specialist clean delta remains the broad-review provenance.

---

Generated by autopilot-pr-merge-worker. This comment is AI-generated and may contain errors.