Skip to content

fix(integration): render, then adopt for every agent writer (#3722) - #3743

Merged
Daniel Meppiel (danielmeppiel) merged 12 commits into
microsoft:mainfrom
MohammedAlkindi:fix/codex-agent-adoption
Nov 17, 2026
Merged

Daniel Meppiel (danielmeppiel) merged 12 commits into
microsoft:mainfrom
MohammedAlkindi:fix/codex-agent-adoption

Conversation

@MohammedAlkindi

@MohammedAlkindi Mohammed Alkindi (MohammedAlkindi) commented Nov 15, 2026 •

Copy link
Copy Markdown
Contributor

Description

A second apm install -g reported APM's own agents as "files skipped" (#3722). With root-local agents in ~/.apm/agents/, no user lockfile records the deployment, so content adoption is the only idempotency path, and three agent writers compared the target against the raw source instead of what they write:

  • Codex: the source .agent.md vs the TOML APM generated (the reporter's case; the issue title said Kiro, the skipped file was Codex).
  • copy_agent (Copilot, Claude, Cursor, OpenCode, ...): the raw source vs the copy whose relative links APM rewrote.
  • Kiro: correct, but via its own inline read_bytes() adoption, a second authority.

Mohammed Alkindi (@MohammedAlkindi)'s original commit (kept) routed Codex through the expected_content seam. This rework, pushed to the same branch, extends that to every agent writer:

  • Owner: BaseIntegrator._check_adopt_or_skip(..., expected_content=rendered). Every agent writer renders first (_render_codex_agent, _preflight_render_kiro_agent, new _render_copy_agent) and hands the text to one helper, AgentIntegrator._deploy_rendered_agent. That helper asks the owner and then writes the same string. Kiro's inline adoption and the deprecated integrate_package_agents try_adopt_identical calls are folded in. The unused _write_kiro_agent writer is removed.
  • Static guard: install-deployment-agent-render-then-adopt is registered on the file-level-deploy-sync-cleanup owner, with a mutation-matrix case. It rejects these calls in agent_integrator.py: is_content_identical_to_source/_text, try_adopt_identical, check_collision, read_bytes, adoption-free writers (copy_agent, _write_codex_agent) in the deploy loop, and write_text_lf outside the helper. It also pins expected_content=rendered followed by write_text_lf(target_path, rendered). The existing install-deployment-codex-agent-link-resolution guard now follows _render_codex_agent.
  • Docs: one sentence in consumer/install-packages.md. CHANGELOG [Unreleased] entry credits the contributor.

Out of scope (per the scope record): F21, which means no user lockfile is written for root-only -g installs. Non-agent writers are also out of scope.

Issue and approved scope

Issue: Fixes #3722

Human scope-approval comment: #3722 (comment)

Does this PR complete the issue, or what remains? Completes the issue. F21 (user lockfile for root-only global installs) is explicitly out of scope and routed to the lockfile owner.

Type of change

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

Testing

  • Tested locally
  • All existing tests pass
  • Added tests for new functionality (if applicable)

New tests:

  • tests/unit/integration/test_agent_integrator.py::TestRenderedAgentAdoption: adoption with managed_files=None for codex, kiro, copilot and claude; foreign edits are still skipped; the legacy multi-target entry point adopts link-rewritten copies.
  • tests/integration/test_global_agent_adoption_lifecycle.py (L6, the red-team oracle, real binary, temp HOME, no network): install -g --force then install -g with codex, kiro, copilot and claude reports nothing skipped. Also covers a link-rewritten agent with copilot and claude.

Fails-before-fix evidence (the same tests run against the unfixed agent_integrator.py):

Code under test Unit TestRenderedAgentAdoption + Codex test L6 lifecycle
main (2769573) 5 failed (codex, copilot, claude, legacy, Codex adopt) 2 failed ("1 file skipped", "2 files skipped")
#3743 original head (a4f6b40) 3 failed (copilot, claude, legacy: link rewrite, F22) 1 failed ("2 files skipped")
this head all pass 2 passed

Kiro passed before the fix because of its inline adoption. The static guard covers that split authority instead: on main and on the original head it reports a violation. Mutation checks (expected_content=None, raw-source adopt, inline read_bytes, copy_agent bypass) each trip the rule.

Validation commands (all run locally on this head):

  • .venv/bin/python -m pytest -p no:xdist -q tests/unit/integration/test_agent_integrator.py tests/unit/integration/test_symlink_rejection.py tests/unit/integration/test_opencode_frontmatter_validation.py tests/integration/test_integrators_validation_rules.py tests/unit/primitives/test_resolve_user_invocable.py: 307 passed
  • .venv/bin/python -m pytest -p no:xdist -q on the 18 other agent-integrator consumer suites (install services, kiro target, content-identical adopt, scope install/uninstall, plugin e2e, install with links, spec conformance manifest reqs, ...): 548 passed, 13 skipped
  • APM_E2E_TESTS=1 APM_BINARY_PATH=$PWD/.venv/bin/apm .venv/bin/python -m pytest tests/integration/test_global_agent_adoption_lifecycle.py -p no:xdist -q: 2 passed
  • .venv/bin/python -m pytest -p no:xdist -q tests/unit/scripts/test_architecture_runner.py tests/integration/test_architecture_owner_rule_mutations.py -k "test_architecture_runner or matrix_covers or case_order or render-then-adopt or codex-agent-link": 80 passed
  • .venv/bin/python -m pytest -p no:xdist -q tests/quality tests/unit/integration/test_agent_integrator.py tests/unit/integration/test_kiro_target.py tests/unit/integration/test_content_identical_adopt.py tests/unit/scripts/test_lifecycle_smoke_sharding.py: 384 passed
  • After merging main (74e5d22): tests/integration/test_wave6_integrators_coverage.py tests/integration/test_wave4_pure_logic_coverage.py: 231 passed
  • Lint contract: uvx ruff@0.15.12 check and format --check on src/ tests/ scripts/lint_architecture_boundaries.py scripts/architecture_linter/ scripts/windows_native_symlink_probe_entry.py passed. Pylint R0801 scored 10.00/10. scripts/lint-auth-signals.sh is clean and scripts/lint-architecture-boundaries.sh exits 0. Files stay under 2100 lines.

Spec conformance (OpenAPM v0.1)

  • Spec edit: docs/src/content/docs/specs/openapm-v0.1.md updated
    (new/changed <a id="req-XXX"></a> anchor + prose + Appendix C
    row).
  • Manifest edit: docs/src/content/docs/specs/manifests/openapm-v0.1.requirements.yml
    updated.
  • Test edit: a @pytest.mark.req("req-XXX") test under
    tests/spec_conformance/ added or extended.
  • CONFORMANCE.{md,json} regenerated via
    uv run --extra dev python -m tests.spec_conformance.gen_statement
    and committed.
  • N/A -- this PR does not change OpenAPM-observable behaviour. (An apm-spec-waiver: line is in the rework commit message.)

Signed-off-by: Mohammed Alkindi <alkndymhmd692@gmail.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.

Copilot was unable to review this pull request because the user who requested the review has insufficient remaining quota. Try requesting a review at a lower effort level.

@danielmeppiel

Copy link
Copy Markdown
Collaborator

Thank you Mohammed Alkindi (@MohammedAlkindi), this is the right seam: routing Codex adoption through expected_content is exactly what the fix needs, and your test is valid. To ship it in 0.36.1, a maintainer lane is extending it so that Kiro's inline adoption and the copy_agent link-rewrite case go through the same render-then-adopt path, and is adding a lifecycle test. The scope record is now on #3722. Your commits will be kept or credited with a Co-authored-by trailer. Your review on the follow-up would be very welcome.

…t#3722)

Codex TOML, Kiro agents and verbatim-copy agents whose relative links
APM rewrites now all render first, ask BaseIntegrator._check_adopt_or_skip
with expected_content=<rendered>, and write that same text through one
AgentIntegrator._deploy_rendered_agent helper. Kiro's inline read_bytes
adoption, the raw-source copy_agent adoption and the deprecated
integrate_package_agents try_adopt_identical calls are folded into the
owner, and the dead _write_kiro_agent writer is removed.

A second `apm install -g` of root-local agents (no lockfile entry) now
adopts APM's own output instead of reporting files skipped.

Guard: install-deployment-agent-render-then-adopt (registered on the
file-level-deploy-sync-cleanup owner) forbids raw adoption/collision
primitives, adoption-free writers and stray write_text_lf in
agent_integrator.py. The Codex link guard now follows _render_codex_agent.

Tests: unit render-then-adopt matrix (codex, kiro, copilot, claude,
foreign edits, legacy entry) and the RT3 L6 lifecycle oracle
(test_global_agent_adoption_lifecycle.py) on the real binary.

apm-spec-waiver: adoption is an internal idempotency fix; no OpenAPM observable contract changes

Co-authored-by: Mohammed Alkindi <alkndymhmd692@gmail.com>
Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com>
Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com>
@danielmeppiel Daniel Meppiel (danielmeppiel) added this to the 0.36.1 milestone Nov 17, 2026
@danielmeppiel Daniel Meppiel (danielmeppiel) changed the title fix(integration): adopt rendered toml on codex agent reinstallation fix(integration): render, then adopt for every agent writer (#3722) Nov 17, 2026
@danielmeppiel

Copy link
Copy Markdown
Collaborator

APM Review Panel: ship_with_followups

Fixes rendered-agent idempotency so a second apm install -g no longer false-skips APM's own Codex TOML and link-rewritten agent copies.

panel-mode=lean; personas=python-architect,test-coverage-expert,apm-ceo

cc Mohammed Alkindi (@MohammedAlkindi) Sergio Sisternes (@sergio-sisternes-epam) -- a fresh advisory pass is ready for your review.

Both panelists agree. The python-architect confirms the single-owner render-then-adopt design is sound. Every agent writer now renders first and adopts through BaseIntegrator._check_adopt_or_skip(expected_content=rendered) via one helper, which removes the class of false skips reported in #3722. The static guard install-deployment-agent-render-then-adopt is mutation-tested, and the deprecated multi-target entry point keeps its behavior. There is no dissent and no blocking-severity finding.

The test-coverage-expert raises one recommended gap. is_content_identical_to_text now decides adoption for every rendered agent, but it has no direct unit tests, while its sibling is_content_identical_to_source has edge-case coverage. The gap predates this PR, but this PR makes the primitive more important. It affects install correctness, not a security-policy surface, so it stays recommended.

Mohammed Alkindi (@MohammedAlkindi) opened the PR with the first fix, and a maintainer lane hardened the design on the same branch, keeping his commit and crediting him in the CHANGELOG.

Aligned with: multi-harness, multi-host (Codex, Kiro and verbatim-copy agent writers share one render-then-adopt path); pragmatic as npm (a second apm install -g is idempotent with no false skips); OSS community-driven (the contributor keeps authorship and changelog credit).

Panel summary

Persona B R N Takeaway
Python Architect 0 0 0 Single-owner render-then-adopt discipline is correct; guard is robust; no blocking regressions in adoption, accounting, or deprecated entry semantics.
Test Coverage Expert 0 1 0 Bug fix well defended by unit matrix, real-binary lifecycle oracle and guard mutation; one recommended gap: direct edge-case tests for the adoption comparison primitive.

B = blocking-severity findings, R = recommended, N = nits.
Counts are signal strength, not gates. The maintainer ships.

Top 1 follow-ups

  1. [Test Coverage Expert] Add direct unit tests for is_content_identical_to_text: CRLF normalization, missing target, symlink target and OSError, mirroring the sibling is_content_identical_to_source tests. -- The primitive now gates idempotency for every rendered-agent adoption path, and an edge-case failure would show up as a silent rewrite or a false skip.

Recommendation

The unit matrix, the real-binary lifecycle oracle and the guard mutation suite back the fix, and both panelists agree it is correct. Ship after the maintainer lane folds the in-scope follow-up, the direct is_content_identical_to_text edge-case tests. The gap predates this PR, but the primitive is now on a hotter path.


Full per-persona findings

Python Architect

No findings.

Test Coverage Expert

  • [recommended] is_content_identical_to_text has no direct unit tests, but this PR makes it the comparison primitive for all rendered-agent adoption via _check_adopt_or_skip(expected_content=...). See tests/unit/integration/test_content_identical_adopt.py.
    The method already existed on main. Its sibling is_content_identical_to_source has edge-case tests for CRLF, symlinks, missing targets and OSError, but grep finds no direct test of the text variant. Indirect coverage comes from TestRenderedAgentAdoption (8 cases).
    Suggested: Add a TestIsContentIdenticalToText class to tests/unit/integration/test_content_identical_adopt.py, mirroring the sibling's edge-case tests and parametrized over lf_normalized_deploy.
    Proof (missing at): tests/unit/integration/test_content_identical_adopt.py::TestIsContentIdenticalToText

This panel is advisory. It does not block merge. Re-apply the
panel-review label after addressing feedback to re-run.


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

…soft#3722)

Folds the review-panel follow-up on microsoft#3743: the rendered-content
comparison behind _check_adopt_or_skip(expected_content=...) now decides
adoption for every agent writer, so pin its LF-normalization, stale CRLF,
missing, symlink and unreadable-target behavior directly. Also correct
the try_adopt_identical docstring, which still named the agent
integrator as a caller.

Co-authored-by: Mohammed Alkindi <alkndymhmd692@gmail.com>
Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com>
Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com>
@danielmeppiel

Copy link
Copy Markdown
Collaborator

APM Review Panel: ship_now

This update closes the last follow-up: is_content_identical_to_text now has 8 direct unit tests, and the docstring makes the adoption boundary clearer.

panel-mode=delta; personas=python-architect,test-coverage-expert,apm-ceo

cc Mohammed Alkindi (@MohammedAlkindi) Sergio Sisternes (@sergio-sisternes-epam) -- a fresh advisory pass is ready for your review.

The previous lean panel on 9eb6c74 recommended one follow-up: direct unit tests for is_content_identical_to_text. This update adds them. TestIsContentIdenticalToText in tests/unit/integration/test_content_identical_adopt.py covers 8 edge cases:

  • LF and CRLF combinations, with and without LF normalization
  • a stale CRLF target that must not be adopted
  • divergent text
  • missing, symlinked and unreadable targets

The try_adopt_identical docstring now lists only byte-preserving callers, which makes the single-owner adoption contract clearer.

Both panelists report no findings, and the test-coverage-expert confirms the earlier gap is closed. On the exact head:

  • 229 unit tests pass and the real-binary lifecycle oracle passes.
  • 80 architecture-runner and mutation cases pass, and the boundary lint is clean.
  • CI showed 21 passing, 2 pending and no failures at last read.

The main-merge commit only touches agent model metadata and does not overlap this change.

Aligned with: portable by manifest (byte-identical adoption keeps installs consistent across harnesses); secure by default (the clearer adoption call-site contract reduces the risk of misuse).

Panel summary

Persona B R N Takeaway
Python Architect 0 0 0 The docstring makes the single-owner adoption boundary clearer; the new unit tests for is_content_identical_to_text cover the key edge cases. No architecture concerns.
Test Coverage Expert 0 0 0 The earlier gap is closed: is_content_identical_to_text now has direct unit tests covering 8 parametrized edge cases. This update adds no new coverage gap.

B = blocking-severity findings, R = recommended, N = nits.
Counts are signal strength, not gates. The maintainer ships.

Recommendation

The previous panel's only follow-up is fixed and backed by passing tests. Both panelists report no findings, CI is green so far, and no new debt surfaced. The stance moves from ship_with_followups to ship_now; the maintainer can merge when ready.


Full per-persona findings

Python Architect

No findings.

Test Coverage Expert

No findings.

This panel is advisory. It does not block merge. Re-apply the
panel-review label after addressing feedback to re-run.


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

Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com>
Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com>
@danielmeppiel

Copy link
Copy Markdown
Collaborator

Folded in this run

  • (panel) The scope fold: the copy_agent link-rewrite case (F22), Kiro's inline adoption and the legacy integrate_package_agents path now all go through _deploy_rendered_agent / _check_adopt_or_skip(expected_content=rendered). The static guard install-deployment-agent-render-then-adopt was added. Resolved in a452c53.
  • (panel) test-coverage-expert: direct unit tests for the edge cases of is_content_identical_to_text; the try_adopt_identical docstring is corrected. Resolved in 2569b90.

Copilot signals reviewed

  • Review 5910320601 (on a4f6b40) -- NOT-LEGIT: it is a quota notice with no review content. Two fetch rounds found no inline Copilot comments.

Regression-trap evidence (mutation-break gate)

  • tests/unit/integration/test_agent_integrator.py::TestRenderedAgentAdoption -- removing render-then-adopt (main's agent_integrator.py) makes this test FAIL as expected (5 failed); guard restored.
  • tests/integration/test_global_agent_adoption_lifecycle.py -- removing render-then-adopt (main and contributor-head versions) makes this test FAIL as expected (2/2 and 1/2); guard restored.
  • tests/integration/test_architecture_owner_rule_mutations.py::test_owner_rule_catches_its_guard_mutation[install-deployment-agent-render-then-adopt] -- changing expected_content=rendered to None triggers the rule as expected; guard restored.

Lint contract

ruff check and ruff format --check (ruff 0.15.12, the version pinned in uv.lock) produce no output on the CI lint paths. pylint R0801 scores 10.00/10, lint-auth-signals is clean and lint-architecture-boundaries exits 0.

CI

All checks are green at the exact head 84d6b77: 23 pass, 3 skipping, 0 pending or failed. This covers Lint, the Build & Test shards, the Lifecycle Smoke shards, the Windows Compatibility Gate, the Spec conformance gate (waived via apm-spec-waiver), the Architecture Ratchet Contracts, CodeQL and gate. That took 3 CI iterations, all main merges or approvals; no CI fixes were needed.

Mergeability status

PR head SHA CEO stance iters folds defers Copilot rounds CI mergeable mergeStateStatus notes
#3743 84d6b77 ship_now 2 2 0 2 green MERGEABLE BLOCKED Awaiting the required review. The owner-touch gate passed (2 owners touched, split-authority-repair, dual guardrail present).

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

Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com>
Avoids landing-order conflicts with other queued PRs.

Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com>
Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com>
@danielmeppiel

Copy link
Copy Markdown
Collaborator

Lane L: main merged for landing

  • Pre-merge head: 84d6b77a7744828a896f1655d84e60c2a33ee882
  • Merged origin/main 82f8047b70b35920f8db9e02940c7e2770c566f2 (clean merge; GitHub reported DIRTY only on CHANGELOG.md, which this repo merges with merge=union).
  • New head: 77a504df336968dcfd53aaaeb1a15d126116db66
  • CHANGELOG: moved 1 bullet(s) in '### Fixed' after entry Integrate copilot runtime #2 of 2, so queued PRs no longer collide at the section head while landing serially.
  • Lint: ruff check + ruff format --check silent at the new head; CI green at the new head.
  • Owner-touch report regenerated at the new head; every recorded functional test was re-run at that exact head and passed (one process at a time, no xdist).
  • Push: git push https://github.com/MohammedAlkindi/apm.git HEAD:refs/heads/fix/codex-agent-adoption (plain push, no force).

This comment was generated by an AI agent (Lane L landing desk) on behalf of Daniel Meppiel (@danielmeppiel).

@danielmeppiel
Daniel Meppiel (danielmeppiel) merged commit c775a7f into microsoft:main Nov 17, 2026
26 checks passed
Daniel Meppiel (danielmeppiel) added a commit that referenced this pull request Nov 18, 2026
Re-verified the sweep's recorded findings on environment-variables,
targets-matrix, install-packages, registries, registry-http-api and
governance-guide against current main (after #3785, #3774, #3782,
#3743, #3797 merged) and fixed what is still drifted.

Refs #3800

Co-authored-by: danielmeppiel <danielmeppiel@users.noreply.github.com>
Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com>
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

Codex agent TOML generated by APM is skipped instead of adopted on subsequent global installs

3 participants