Repository navigation
fix(mcp): render remote transports per harness and heal retired shapes - #3789
Daniel Meppiel (danielmeppiel) merged 10 commits into
Conversation
Registry v0.1 remotes carry `type` (streamable-http or sse), but APM read only the legacy `transport_type`, so SSE servers were rendered as Streamable HTTP on every harness, Antigravity inherited Gemini's `httpUrl` (which it rejects), and Codex SSE aborted the install. - New owner mcp_transport.canonical_remote_transport normalizes v0.1 `type`, legacy `transport_type` and manifest `transport`; registry ingestion, self-defined servers and overlays record remote["transport"]. Adapters and `apm mcp show` read only through it. - New owner adapters/client/_remote_shapes.py: one evidence-backed row per ClientFactory runtime, bound in each adapter's own class body. Copilot/Claude/VS Code SSE -> type sse; Gemini SSE -> url; Antigravity -> serverUrl; SSE on Antigravity/Codex -> warn once, skip, not claimed, exit 0 (also under --frozen). Hermes keeps today's output (#3749). - Ownership owner heals APM-written entries in a retired shape (legacy_managed_renders) and removes an APM-owned entry whose transport the harness now refuses; foreign entries stay preserved. - httpUrl and serverUrl join the MCP passthrough denylist. - Static guards: mcp-remote-transport-normalization and mcp-remote-shape-table (hooks-integrations shard) with mutation cases. apm-spec-waiver: harness-native MCP output shapes are not pinned by OpenAPM v0.1 (native docs decide; req-mf-012 covers declarations only) Fixes #3736 Fixes #3711 Co-authored-by: Mohammed Alkindi <alkndymhmd692@gmail.com> Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com>
…l-t3-p1-mcp-remote-transport
Co-authored-by: Mohammed Alkindi <alkndymhmd692@gmail.com> Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com>
APM Review Panel:
|
| Persona | B | R | N | Takeaway |
|---|---|---|---|---|
| Python Architect | 0 | 2 | 0 | Two new canonical owners well-guarded; two hidden-state patterns worth hardening before Hermes row followup. |
| Test Coverage Expert | 0 | 2 | 0 | Critical harness/heal/frozen promises well covered at integration tier; one cross-module frozen ContextVar path untested, one supply-chain denylist layer gap. |
| Supply Chain Security Expert | 0 | 0 | 0 | Denylist, ownership-proof, and frozen-boundary changes are sound; no passthrough bypass, no user-entry misattribution, no credential leak. |
B = blocking-severity findings, R = recommended, N = nits.
Counts are signal strength, not gates. The maintainer ships.
Top 4 follow-ups
- [Test Coverage Expert] Add from_dict unit test for httpUrl and serverUrl denylist entries -- Defense-in-depth gap on a secure-by-default surface; a unit test at the parsing boundary survives refactors the other guards might not.
- [Python Architect] Declare _remote_shape_override and _comparison_render_depth on MCPClientAdapter -- The hidden cross-module protocol will widen with the Hermes row follow-up ([BUG] Hermes MCP adapter drops cwd, extra passthrough keys and the SSE transport when writing config.yaml #3749).
- [Python Architect] Replace synthesized fingerprint in _skip_unsupported_remote_transport with an explicit proven-ownership input -- Eliminates a dual-authority removal path that could survive a future tightening of remove_stale.
- [Test Coverage Expert] Rename or annotate the frozen-replay test to surface its ContextVar deferred-pair coverage intent -- The path is exercised; the name should say so.
Recommendation
All three specialists converged with zero blocking findings and the supply-chain expert gave a clean pass on the highest-risk surface. Ship when CI is green. Track the from_dict denylist unit test (defense-in-depth on secure-by-default) and the hidden-attribute declaration (readability debt before #3749) as near-term items.
Full per-persona findings
Python Architect
- [recommended] Undeclared mutable-state protocol: _remote_shape_override and _comparison_render_depth are hidden instance attributes at
src/apm_cli/adapters/client/base.py:406
base.py sets both dynamically; _remote_shapes.py reads them via getattr defaults. A refactor (or slots) would not see them.
Suggested: Declare both on MCPClientAdapter and read them directly. - [recommended] Synthesized fingerprint in _skip_unsupported_remote_transport creates a dual-authority removal path at
src/apm_cli/integration/mcp_integrator_install.py:620
Ownership is proven by managed_unsupported_connection, then a self-matching hash lets require_removable_mcp_connections pass; a later tightening of that authority would be bypassed here.
Suggested: Give the removal owner an explicit proven-ownership input instead of a tautological hash.
Test Coverage Expert
- [recommended] Deferred frozen pair that turns out supported (ContextVar handoff) has no test exercising the error raise at
tests/integration/test_mcp_remote_transport_harness_lifecycle.py
The arm is exercised by the existing e2e test (undeclared transport on codex is deferred, then refused); only its intent is not named in the test.
Proof (passed):tests/integration/test_mcp_remote_transport_harness_lifecycle.py::test_frozen_replay_still_refuses_an_unrecorded_supported_target-- proves: A frozen install never writes a claim the lockfile does not record, even for a deferred pair - [recommended] httpUrl/serverUrl denylist addition has no from_dict layer test (adapter render layer is tested) at
tests/unit/test_mcp_from_dict_unknown_keys.py
TestExtraReservedKeyDenylist covers command/env/http_headers but not the two new aliases. Defense in depth.
Proof (missing at):tests/unit/test_mcp_from_dict_unknown_keys.py-- proves: A manifest author cannot smuggle httpUrl or serverUrl through extra
Supply Chain Security 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.
There was a problem hiding this comment.
🟡 Changes recommended
Unresolved ownership and cleanup flaws can overwrite or delete user-managed MCP entries, alter native configs during rejected frozen installs, and discard ownership after failed cleanup.
5 open issues
Add new rule IDs to the frozen test inventory · New Do not infer retired-entry ownership after a fingerprint mismatch · New Resolve all deferred ownership checks before modifying native configs · New Validate ownership of each Antigravity key before deletion · New Preserve ownership when stale-entry cleanup fails · New
What changed in this PR
This PR centralizes remote MCP transport handling and harness-specific configuration formats, addressing registry transport detection (#3736) and Antigravity endpoint keys (#3711). It also adds migration handling for configurations written by earlier APM releases.
Changes:
- Normalize remote transports and render each harness's native configuration.
- Heal retired managed formats and skip unsupported transports, including during frozen installs.
- Add regression tests, upgrade fixtures, architecture guards, and documentation.
| File | Description |
|---|---|
tests/unit/test_vscode_adapter.py |
Expect native http transport output. |
tests/unit/test_mcp_overlays.py |
Assert canonical transport fields. |
tests/unit/test_mcp_integrator_phase3w4.py |
Update SSE normalization expectation. |
tests/unit/test_mcp_integrator_overlay.py |
Update SSE normalization expectation. |
tests/unit/test_mcp_client_factory.py |
Patch the shared warning helper. |
tests/unit/test_copilot_adapter.py |
Expect distinct SSE output. |
tests/unit/integration/test_mcp_integrator.py |
Assert normalized HTTP transports. |
tests/unit/install/test_mcp_retired_shape_heal.py |
Cover ownership-aware format migration. |
tests/unit/adapters/test_mcp_remote_transport_shapes.py |
Cover normalization and harness formats. |
tests/integration/test_mcp_remote_transport_harness_lifecycle.py |
Exercise rendering and frozen replay. |
tests/integration/test_mcp_integrator_install_flow.py |
Update canonical transport assertions. |
tests/integration/test_mcp_integrator_characterisation.py |
Update normalized remote expectations. |
tests/integration/test_download_copilot_end_to_end.py |
Expect Copilot SSE output. |
tests/integration/test_architecture_owner_rule_mutations.py |
Add transport and format guard mutations. |
tests/integration/_harness_output_kit.py |
Share isolated harness test infrastructure. |
tests/fixtures/upgrade_0361/t3/v0.36.0/user-mcp/home/.hermes/config.yaml |
Capture legacy user Hermes configuration. |
tests/fixtures/upgrade_0361/t3/v0.36.0/user-mcp/home/.gemini/settings.json |
Capture legacy user Gemini configuration. |
tests/fixtures/upgrade_0361/t3/v0.36.0/user-mcp/home/.gemini/config/mcp_config.json |
Capture legacy user Antigravity configuration. |
tests/fixtures/upgrade_0361/t3/v0.36.0/user-mcp/home/.claude.json |
Capture legacy user Claude configuration. |
tests/fixtures/upgrade_0361/t3/v0.36.0/user-mcp/home/.apm/apm.yml |
Define user MCP upgrade inputs. |
tests/fixtures/upgrade_0361/t3/v0.36.0/user-mcp/home/.apm/apm.lock.yaml |
Record user MCP ownership baseline. |
tests/fixtures/upgrade_0361/t3/v0.36.0/user-agents/home/.kiro/agents/kit-agent.md |
Capture legacy Kiro agent output. |
tests/fixtures/upgrade_0361/t3/v0.36.0/user-agents/home/.codex/agents/kit-agent.toml |
Capture legacy Codex agent output. |
tests/fixtures/upgrade_0361/t3/v0.36.0/user-agents/home/.claude/agents/kit-agent.md |
Capture legacy Claude agent output. |
tests/fixtures/upgrade_0361/t3/v0.36.0/user-agents/home/.apm/apm.yml |
Define user agent fixture profile. |
tests/fixtures/upgrade_0361/t3/v0.36.0/user-agents/home/.apm/agents/kit-agent.agent.md |
Supply source agent fixture. |
tests/fixtures/upgrade_0361/t3/v0.36.0/project-mcp/project/apm.yml |
Define project MCP upgrade inputs. |
tests/fixtures/upgrade_0361/t3/v0.36.0/project-mcp/project/apm.lock.yaml |
Record project MCP ownership baseline. |
tests/fixtures/upgrade_0361/t3/v0.36.0/project-mcp/project/.vscode/mcp.json |
Capture retired VS Code formats. |
tests/fixtures/upgrade_0361/t3/v0.36.0/project-mcp/project/.mcp.json |
Capture legacy project Claude configuration. |
tests/fixtures/upgrade_0361/t3/v0.36.0/project-mcp/project/.github/mcp.json |
Capture legacy project Copilot configuration. |
tests/fixtures/upgrade_0361/t3/v0.36.0/project-mcp/project/.gemini/settings.json |
Capture legacy project Gemini configuration. |
tests/fixtures/upgrade_0361/t3/v0.36.0/project-mcp/project/.agents/mcp_config.json |
Capture retired Antigravity endpoint keys. |
tests/fixtures/upgrade_0361/t3/v0.36.0/project-mcp/home/.hermes/config.yaml |
Capture Hermes configuration baseline. |
tests/fixtures/upgrade_0361/t3/v0.36.0/project-codex/project/apm.yml |
Define Codex upgrade inputs. |
tests/fixtures/upgrade_0361/t3/v0.36.0/project-codex/project/apm.lock.yaml |
Record Codex ownership baseline. |
tests/fixtures/upgrade_0361/t3/v0.36.0/project-codex/project/.codex/config.toml |
Capture stale Codex SSE entry. |
tests/fixtures/upgrade_0361/t3/v0.35.1/user-mcp/home/.hermes/config.yaml |
Capture legacy user Hermes configuration. |
tests/fixtures/upgrade_0361/t3/v0.35.1/user-mcp/home/.gemini/settings.json |
Capture legacy user Gemini configuration. |
tests/fixtures/upgrade_0361/t3/v0.35.1/user-mcp/home/.gemini/config/mcp_config.json |
Capture legacy user Antigravity configuration. |
tests/fixtures/upgrade_0361/t3/v0.35.1/user-mcp/home/.claude.json |
Capture legacy user Claude configuration. |
tests/fixtures/upgrade_0361/t3/v0.35.1/user-mcp/home/.apm/apm.yml |
Define user MCP upgrade inputs. |
tests/fixtures/upgrade_0361/t3/v0.35.1/user-mcp/home/.apm/apm.lock.yaml |
Supply older user ownership baseline. |
tests/fixtures/upgrade_0361/t3/v0.35.1/user-agents/home/.kiro/agents/kit-agent.md |
Capture legacy Kiro agent output. |
tests/fixtures/upgrade_0361/t3/v0.35.1/user-agents/home/.codex/agents/kit-agent.toml |
Capture legacy Codex agent output. |
tests/fixtures/upgrade_0361/t3/v0.35.1/user-agents/home/.claude/agents/kit-agent.md |
Capture legacy Claude agent output. |
tests/fixtures/upgrade_0361/t3/v0.35.1/user-agents/home/.apm/apm.yml |
Define user agent fixture profile. |
tests/fixtures/upgrade_0361/t3/v0.35.1/user-agents/home/.apm/agents/kit-agent.agent.md |
Supply source agent fixture. |
tests/fixtures/upgrade_0361/t3/v0.35.1/project-mcp/project/apm.yml |
Define project MCP upgrade inputs. |
tests/fixtures/upgrade_0361/t3/v0.35.1/project-mcp/project/apm.lock.yaml |
Supply older project ownership baseline. |
tests/fixtures/upgrade_0361/t3/v0.35.1/project-mcp/project/.vscode/mcp.json |
Capture retired VS Code formats. |
tests/fixtures/upgrade_0361/t3/v0.35.1/project-mcp/project/.mcp.json |
Capture legacy project Claude configuration. |
tests/fixtures/upgrade_0361/t3/v0.35.1/project-mcp/project/.github/mcp.json |
Capture legacy project Copilot configuration. |
tests/fixtures/upgrade_0361/t3/v0.35.1/project-mcp/project/.gemini/settings.json |
Capture legacy project Gemini configuration. |
tests/fixtures/upgrade_0361/t3/v0.35.1/project-mcp/project/.agents/mcp_config.json |
Capture retired Antigravity endpoint keys. |
tests/fixtures/upgrade_0361/t3/v0.35.1/project-mcp/home/.hermes/config.yaml |
Capture Hermes configuration baseline. |
tests/fixtures/upgrade_0361/t3/v0.35.1/project-codex/project/apm.yml |
Define Codex upgrade inputs. |
tests/fixtures/upgrade_0361/t3/v0.35.1/project-codex/project/apm.lock.yaml |
Supply older Codex ownership baseline. |
tests/fixtures/upgrade_0361/t3/v0.35.1/project-codex/project/.codex/config.toml |
Capture stale Codex SSE entry. |
tests/fixtures/upgrade_0361/t3/README.md |
Document fixture provenance and regeneration. |
tests/fixtures/upgrade_0361/t3/generate_fixtures.py |
Generate isolated release upgrade fixtures. |
src/apm_cli/registry/client.py |
Normalize registry remote transports. |
src/apm_cli/models/dependency/mcp.py |
Reserve harness endpoint aliases. |
src/apm_cli/mcp_transport.py |
Own transport vocabulary and precedence. |
src/apm_cli/integration/mcp_integrator.py |
Normalize declarations and select matching remotes. |
src/apm_cli/integration/mcp_integrator_install.py |
Skip unsupported transports and clean retired entries. |
src/apm_cli/install/service.py |
Defer eligible frozen ownership checks. |
src/apm_cli/install/service_integration.py |
Carry deferred pairs through MCP integration. |
src/apm_cli/install/mcp/ownership.py |
Recognize retired formats and managed cleanup candidates. |
src/apm_cli/commands/mcp.py |
Display canonical remote transports. |
src/apm_cli/adapters/client/windsurf.py |
Bind an explicit Windsurf format. |
src/apm_cli/adapters/client/vscode.py |
Render normalized VS Code transports. |
src/apm_cli/adapters/client/opencode.py |
Bind an explicit OpenCode format. |
src/apm_cli/adapters/client/kiro.py |
Use shared normalization and rendering. |
src/apm_cli/adapters/client/intellij.py |
Bind an explicit IntelliJ format. |
src/apm_cli/adapters/client/hermes.py |
Bind the unchanged Hermes format. |
src/apm_cli/adapters/client/gemini.py |
Use shared formats and unsupported handling. |
src/apm_cli/adapters/client/cursor.py |
Use shared normalization and rendering. |
src/apm_cli/adapters/client/copilot.py |
Render distinct HTTP and SSE formats. |
src/apm_cli/adapters/client/codex.py |
Detect unsupported SSE through normalization. |
src/apm_cli/adapters/client/claude.py |
Bind Claude's HTTP and SSE formats. |
src/apm_cli/adapters/client/base.py |
Render retired formats for ownership comparison. |
src/apm_cli/adapters/client/antigravity.py |
Bind Antigravity-specific endpoint handling. |
src/apm_cli/adapters/client/_remote_shapes.py |
Own current, retired, and unsupported formats. |
scripts/architecture_linter/groups/mutation_writes.py |
Register new architecture checks. |
scripts/architecture_linter/checks/mutation_mcp_target_and_scope.py |
Extend endpoint-alias denylist guard. |
scripts/architecture_linter/checks/mutation_mcp_remote_transport.py |
Guard transport ownership and adapter bindings. |
packages/apm-guide/.apm/skills/apm-usage/dependencies.md |
Explain transport formats and migration behavior. |
docs/src/content/docs/reference/manifest-schema.md |
Document reserved endpoint aliases. |
docs/src/content/docs/consumer/install-mcp-servers.md |
Describe harness transport support and healing. |
CHANGELOG.md |
Summarize the remote MCP fixes. |
.apm/architecture/owners/hooks-integrations.json |
Register transport and format owners. |
Review effort: Balanced
- Declare _remote_shape_override and _comparison_render_depth on MCPClientAdapter instead of hidden instance attributes. - require_removable_mcp_connections accepts an explicit proven_owned input (entry still identical to the one the ownership owner proved); the unsupported-transport removal passes it instead of a synthesized fingerprint. - from_dict test for httpUrl/serverUrl denylist aliases; rename the frozen test that covers the deferred-then-supported arm. Co-authored-by: Mohammed Alkindi <alkndymhmd692@gmail.com> Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com>
- A recorded fingerprint that does not match blocks retired-render ownership inference (heal and unsupported-transport removal), so an entry edited after APM wrote it is never overwritten or deleted. - --frozen resolves every deferred (server, runtime) pair against its overlaid registry payload before any native write; a refused replay changes no native config. - An APM-owned entry for a now-refused transport is removed by its exact native key with fail_on_write_error, and the claim is dropped only after the removal succeeds (no broad remove_stale expansion). - Register the two new rule IDs in the frozen runner inventory test. Co-authored-by: Mohammed Alkindi <alkndymhmd692@gmail.com> Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com>
- _overlaid_server_infos owns fetching registry server info and applying each declaration's overlay (on deep copies); the install loop and the --frozen deferred-pair pre-resolution both use it. - Unit trap: a failed removal of an APM-owned entry for a refused transport keeps the ownership claim for a retry. Co-authored-by: Mohammed Alkindi <alkndymhmd692@gmail.com> Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com>
…rgets Co-authored-by: Mohammed Alkindi <alkndymhmd692@gmail.com> Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com>
APM Review Panel:
|
| Persona | B | R | N | Takeaway |
|---|---|---|---|---|
| Python Architect | 0 | 1 | 0 | Frozen pre-resolution duplicated the fetch-overlay pipeline (folded); single-owner discipline otherwise clean. |
| Test Coverage Expert | 0 | 1 | 0 | Frozen pre-resolution and exact-key removal have e2e traps; claim preservation on write failure now trapped (folded). |
| Supply Chain Security Expert | 0 | 1 | 0 | Fingerprint-mismatch guard and verified-key removal are sound; frozen registry lookup documented (folded). |
B = blocking-severity findings, R = recommended, N = nits.
Counts are signal strength, not gates. The maintainer ships.
Recommendation
All three delta findings are resolved -- two folded with code and tests, one answered with a rationale and a doc note. CI was fully green on b897e6b (23 checks); the latest head re-runs the same suite. Ready for CODEOWNER review for 0.36.1.
Full per-persona findings
Python Architect
- [recommended] _resolve_frozen_deferred_pairs inlines a second copy of the registry-fetch + overlay orchestration at
src/apm_cli/integration/mcp_integrator_install.py
Two copies of group -> batch fetch -> deepcopy -> overlay; a future step added to one could diverge.
Suggested: Extract one helper used by both paths. (Folded in eca4f54.)
Test Coverage Expert
- [recommended] No regression trap for fail-loud removal preserving the ownership claim on write failure at
tests/unit/install/test_mcp_retired_shape_heal.py
Moving claims.discard before the removal would silently orphan an entry.
Proof (missing at):tests/unit/install/test_mcp_retired_shape_heal.py-- proves: A write failure during unsupported-transport removal preserves the ownership claim (added in eca4f54).
Supply Chain Security Expert
- [recommended] _resolve_frozen_deferred_pairs contacts manifest-authored registry URLs during --frozen installs at
src/apm_cli/integration/mcp_integrator_install.py
Egress under --frozen; fail-closed, integrity preserved.
Suggested: Refuse deferred pairs without fetching, gate behind opt-in, or document. (Documented in 44ea93d.)
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-merge-worker. This comment is AI-generated and may contain errors.
…ersion - .gitignore re-includes tests/fixtures/upgrade_0361/**/.copilot/ so the user-scope Copilot MCP and agent state the heal tests seed is tracked (it was silently ignored, letting those cases pass vacuously in CI). - generate_fixtures.py also pins importlib.metadata's apm-cli version, so the v0.35.1 lockfiles record apm_version 0.35.1; both sets were regenerated from the tagged sources (no other byte changed). Co-authored-by: Mohammed Alkindi <alkndymhmd692@gmail.com> Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com>
Takes the red-team versions verbatim (e21018501c, 0e8c812100): the .gitignore negation comment and generator pin wording, and the heal oracle that runs audit --ci straight after the upgrade command so the #3781 user-update cases are a strict xfail instead of being masked by a later install. The Hermes assertions stay deferred to #3749. Co-authored-by: Mohammed Alkindi <alkndymhmd692@gmail.com> Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com>
…l-t3-p1-mcp-remote-transport
…allback Delta panel folds for #3788 (stacked on #3789): - When the registry could not be read during the policy check, policy judges the declared transport and records it; install now re-projects the overlaid info it would write and refuses, before any write in the group, when the result differs (unverified_policy_fallbacks). - server_write_transports takes the adapters' remote selector from the caller, so the owner module no longer imports the adapter layer; the owner record lists the policy symbols and the guard pins the definition site and the install refusal. - Tests: flaky-registry fallback refusal, multi-remote projection, every-adapter remote parity, snapshot reuse on a per-dependency registry, and `install --mcp --registry` resolving policy against the flag's registry (lifecycle). Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com>
…allback Delta panel folds for #3788 (stacked on #3789): - When the registry could not be read during the policy check, policy judges the declared transport and records it; install now re-projects the overlaid info it would write and refuses, before any write in the group, when the result differs (unverified_policy_fallbacks). - server_write_transports takes the adapters' remote selector from the caller, so the owner module no longer imports the adapter layer; the owner record lists the policy symbols and the guard pins the definition site and the install refusal. - Tests: flaky-registry fallback refusal, multi-remote projection, every-adapter remote parity, snapshot reuse on a per-dependency registry, and `install --mcp --registry` resolving policy against the flag's registry (lifecycle). Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com>
…allback Delta panel folds for #3788 (stacked on #3789): - When the registry could not be read during the policy check, policy judges the declared transport and records it; install now re-projects the overlaid info it would write and refuses, before any write in the group, when the result differs (unverified_policy_fallbacks). - server_write_transports takes the adapters' remote selector from the caller, so the owner module no longer imports the adapter layer; the owner record lists the policy symbols and the guard pins the definition site and the install refusal. - Tests: flaky-registry fallback refusal, multi-remote projection, every-adapter remote parity, snapshot reuse on a per-dependency registry, and `install --mcp --registry` resolving policy against the flag's registry (lifecycle). Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com>
#3789 landed the RT3 retired-shape heal lifecycle with a strict xfail on the user `update -g` then `audit --ci` cases. With the #3781 fix those cases pass for real (12 passed incl. user-v0.35.1-update and user-v0.36.0-update), so the xfail marker, its sentinel exception and the special-case raise go. .gitignore keeps both fixture-tree `.copilot/` negations. Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com>
…allback Delta panel folds for #3788 (stacked on #3789): - When the registry could not be read during the policy check, policy judges the declared transport and records it; install now re-projects the overlaid info it would write and refuses, before any write in the group, when the result differs (unverified_policy_fallbacks). - server_write_transports takes the adapters' remote selector from the caller, so the owner module no longer imports the adapter layer; the owner record lists the policy symbols and the guard pins the definition site and the install refusal. - Tests: flaky-registry fallback refusal, multi-remote projection, every-adapter remote parity, snapshot reuse on a per-dependency registry, and `install --mcp --registry` resolving policy against the flag's registry (lifecycle). Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com>
…allback Delta panel folds for #3788 (stacked on #3789): - When the registry could not be read during the policy check, policy judges the declared transport and records it; install now re-projects the overlaid info it would write and refuses, before any write in the group, when the result differs (unverified_policy_fallbacks). - server_write_transports takes the adapters' remote selector from the caller, so the owner module no longer imports the adapter layer; the owner record lists the policy symbols and the guard pins the definition site and the install refusal. - Tests: flaky-registry fallback refusal, multi-remote projection, every-adapter remote parity, snapshot reuse on a per-dependency registry, and `install --mcp --registry` resolving policy against the flag's registry (lifecycle). Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com>
…allback Delta panel folds for #3788 (stacked on #3789): - When the registry could not be read during the policy check, policy judges the declared transport and records it; install now re-projects the overlaid info it would write and refuses, before any write in the group, when the result differs (unverified_policy_fallbacks). - server_write_transports takes the adapters' remote selector from the caller, so the owner module no longer imports the adapter layer; the owner record lists the policy symbols and the guard pins the definition site and the install refusal. - Tests: flaky-registry fallback refusal, multi-remote projection, every-adapter remote parity, snapshot reuse on a per-dependency registry, and `install --mcp --registry` resolving policy against the flag's registry (lifecycle). Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com>
…#3788) * fix(policy): check mcp.transport.allow on the effective MCP transport Org policy mcp.transport.allow compared only the transport declared in apm.yml, so a registry server with no declared transport (for example an SSE remote) was never checked, and `http` did not match `streamable-http`. - mcp_transport.py (owner) gains the policy projection: canonical_transport_name(s), POLICY_TRANSPORTS, UnresolvedTransport and server_write_transports (package = stdio, the adapter-selected remote = its canonical transport, both for dual servers). - The parser canonicalizes mcp.transport.allow once; inheritance intersects canonical names; unknown names warn. - run_dependency_policy_checks resolves effective transports through integration/mcp_transport_resolution.py, which reuses install's _registry_group_key and _overlaid_server_infos: registry servers are looked up in the registry install uses and judged on the overlaid info (a declared transport narrows only when offered; it is the offline fallback when the registry cannot resolve the server). Self-defined servers resolve offline. Deps dedupe first-wins as install does. The lookup runs only when mcp.transport.allow is set; unresolvable servers fail with an actionable reason. - Install writes the registry snapshot policy judged (policy_checked_registry_info); `apm install --mcp` runs its preflight against the --registry endpoint before apm.yml is written; audit --ci checks production and dev MCP servers like the install gate. - Guard install-deployment-policy-mcp-transport-projection (owner record and MutationCase) bans raw transport reads under policy/ and pins the routing. Fixes #3764 apm-spec-waiver: org policy evaluation only; no OpenAPM manifest, lockfile or registry contract change Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com> * fix(policy): refuse unchecked transports after a declared-transport fallback Delta panel folds for #3788 (stacked on #3789): - When the registry could not be read during the policy check, policy judges the declared transport and records it; install now re-projects the overlaid info it would write and refuses, before any write in the group, when the result differs (unverified_policy_fallbacks). - server_write_transports takes the adapters' remote selector from the caller, so the owner module no longer imports the adapter layer; the owner record lists the policy symbols and the guard pins the definition site and the install refusal. - Tests: flaky-registry fallback refusal, multi-remote projection, every-adapter remote parity, snapshot reuse on a per-dependency registry, and `install --mcp --registry` resolving policy against the flag's registry (lifecycle). Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com> * fix(policy): judge registry servers only on registry data Copilot review folds for #3788: the declared-transport fallback let `install --mcp --transport ...` write apm.yml before the later refusal fired, and the install-side refusal bypassed enforcement: warn. A registry server is now always judged on the registry data install writes from; when the registry cannot resolve it the transport is unknown, which the shared enforcement path blocks (block) or warns about (warn) before any write. Self-defined servers still resolve offline. The install-side refusal is removed. Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com> * test(policy): assert unknown MCP transport warns under enforcement warn Takeover folds for #3788: the warn-mode regression now asserts the `effective transport unknown` violation is recorded with severity warn (not only that preflight returns), and the check-9 resolver docstring states that every registry server is looked up, declared or not. apm-spec-waiver: org policy evaluation only; no OpenAPM manifest, lockfile or registry contract change Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com> * test(policy): pin the transport remedy and audit verdicts for #3764 Delta panel folds (test-coverage-expert) for #3788: - Unit: a server offering sse and streamable-http remotes is judged on the sse remote install writes when undeclared, and `transport: http` (or `streamable-http`) picks the allowed remote. Replaces an alias test that passed whether or not the alias narrowed anything. - Lifecycle: `apm audit --ci` with an unreachable registry reports a registry server that declares `transport:` as unknown, and `enforcement: warn` downgrades that check to a reported warning. apm-spec-waiver: org policy evaluation only; no OpenAPM manifest, lockfile or registry contract change Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com> * fix(policy): say why a declared transport cannot settle an unknown one Captain fold for #3788: the `effective transport unknown` violation now explains that a declared `transport:` is not enough for a registry server, because install writes the transport the registry serves and `transport:` only picks among the ones it offers. Unit and lifecycle tests pin the wording. apm-spec-waiver: org policy evaluation only; no OpenAPM manifest, lockfile or registry contract change Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com> * fix(policy): lead the unknown-transport violation with the remedy Delta panel fold (cli-logging-expert) for #3788: the `effective transport unknown` detail now says what to do (check the server name and registry URL, or make the MCP registry reachable, then retry) before the short reason a declared 'transport:' cannot stand in, in short sentences and with the check's single-quote style. apm-spec-waiver: org policy evaluation only; no OpenAPM manifest, lockfile or registry contract change Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com> * docs(changelog): file #3788 under [Unreleased] The rebase onto main placed the #3788 entry (twice) inside the [0.36.1] block and duplicated two 0.36.1 entries; keep main's CHANGELOG and add the current #3788 entry once under [Unreleased]. Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com> * refactor(install): pass the --mcp policy registry as one (url, source) pair main's commands/install.py sits at the 2100-line CI cap; the two new keyword arguments for the --mcp policy preflight pushed it to 2102. run_mcp_policy_preflight now takes the (url, source) pair _resolve_registry_url returns. No behavior change. apm-spec-waiver: org policy evaluation only; no OpenAPM manifest, lockfile or registry contract change Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com> * Merge main (0199ded) into #3788; slot CHANGELOG bullet Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com> --------- Co-authored-by: danielmeppiel <danielmeppiel@users.noreply.github.com> Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com>

Description
Remote MCP servers now reach each harness in its native shape, and installs written by APM 0.35/0.36 heal on the next command.
Root cause: three missing owners. (1) Registry v0.1 remotes carry
type(streamable-httporsse), but six adapters andapm mcp showread only the legacytransport_type, each defaulting to HTTP, so every registry SSE remote was rendered as Streamable HTTP. (2) Remote output shapes came from class inheritance, so Antigravity silently inherited Gemini'shttpUrl(Antigravity rejects it) and Copilot-family SSE was alwaystype: http. (3) The ownership owner treated an unchanged declaration as "already configured", so a renderer fix alone would leave old entries stale (fingerprint present) or report a false conflict (no fingerprint).What changes:
src/apm_cli/mcp_transport.py:canonical_remote_transport(remote)plusTRANSPORT_STREAMABLE_HTTP,TRANSPORT_SSE,CANONICAL_REMOTE_TRANSPORTS. Precedence: v0.1type, then legacytransport_type, then manifesttransport;httpaliases Streamable HTTP; missing means Streamable HTTP; unknown raises today's error text; atype/transport_typedisagreement usestype(debug log). Ingestion (registry/client.py::_normalize_v0_1_server,_build_self_defined_info,_apply_overlay) recordsremote["transport"]. All adapters andapm mcp showread only through the owner._apply_overlayalso prefers the remote matching a declared remote transport.src/apm_cli/adapters/client/_remote_shapes.py: one frozen, evidence-backedRemoteShaperow perClientFactoryruntime, bound in each adapter's own class body (remote_shape = remote_shape_row("<runtime>")), so a subclass can no longer inherit a parent's shape. Unverified rows are listed inUNVERIFIED_REMOTE_SHAPES(cursor, hermes, intellij, kiro, opencode, windsurf).[!]warning naming server and harness, is skipped before any comparison or write, is not claimed, and exits0; other servers and runtimes still install. Fixes the RT3 finding where Codex SSE aborted with "Adapter did not produce a native MCP server mapping".MCPClientAdapter.legacy_managed_renders(info)renders the declaration with each retired shape of the adapter's row;compare_native_mcp_connectionreturnsUPDATE_MANAGEDfor a managed entry in a retired shape (exact legacy render, or fingerprint plus legacy remote keys) even when the declaration is unchanged. Env-only differences on non-refreshing adapters stayMATCHING_MANAGED; foreign entries stayCONFLICT. An APM-owned entry whose transport the harness now refuses (0.36 Antigravity/Codex SSE) is removed by its exact native key (failing loudly on write errors) and its claim dropped only after removal (F-RT3-7). A recorded fingerprint that no longer matches blocks every earlier-render inference, so entries edited after APM wrote them are preserved. The Codex hardcoded migration is untouched.--frozen: a pair the lock records the server for but never claimed (because the harness refuses the transport) and whose native config has no entry is skipped with the same warning; every deferred pair is resolved against its registry payload before any native write; a pair the harness can load raises the same "ownership is not recorded" error as before and nothing is written (documented IntelliJ contract preserved). Under--frozenthe lock stays byte-identical; the next plain install records dropped claims.httpUrlandserverUrljoin_HARNESS_EXTRA_ALIASES(transport/typewere already reserved).mcp-remote-transport-normalizationandmcp-remote-shape-table(hooks-integrations shard), rulesmutation_writes.mcp_remote_transport_normalization(bans"transport_type"andremote.get("type")undersrc/apm_cli/adapters/**andcommands/mcp.py; requires ingestion through the owner) andmutation_writes.mcp_remote_shape_table(every registered runtime binds its own row, every row cites evidence, unverified list matches). Both have mutation cases.Harness x transport after this PR:
type: http,urltype: sse,url(was http)type: http(self-definedstreamable-httpwas written verbatim)type: sse(registry was http)type: httptype: sse(was http)httpUrlurl(registry was httpUrl)serverUrl(was httpUrl)urlurl)Supersedes #3741 (credit: Co-authored-by Mohammed Alkindi).
Issue and approved scope
Issue: Fixes #3736
Issue: Fixes #3711 (part 1 was refuted by the reporter; part 2 is fully fixed here)
Human scope-approval comment: #3736 (comment) and #3711 (comment)
Does this PR complete the issue, or what remains? Completes both. Out of scope by decision: policy
mcp.transport.allowon the effective (normalized) transport (H1, 0.37), the Hermes row (#3749, builds on this owner), generalizing the Codex hardcoded migration. Known pre-existing, unrelated:apm update -gfollowed byapm audit --cireports missing~/.apm/apm_modules(reproduced on v0.36.0; 2 RT3 cases xfail against it).Type of change
Testing
New tests:
tests/unit/adapters/test_mcp_remote_transport_shapes.py: T-norm table (v0.1 sse/streamable-http, legacy,httpalias, missing, unknown, conflict), ingestion, golden render per runtime x transport, own-row binding, unsupported disposition, denylist.tests/unit/install/test_mcp_retired_shape_heal.pyandtests/unit/test_mcp_from_dict_unknown_keys.py: heal matrix (fingerprint + retired, legacy render without fingerprint, foreign, env-only no churn, unrecognized), VS Codestreamable-httpalias, removal of a retired self-defined entry, a mismatching fingerprint never lets an earlier render claim an edited entry, the unsupported-transport removal deletes only the verified exact key,from_dictstripshttpUrl/serverUrl.tests/integration/test_mcp_remote_transport_harness_lifecycle.py(RT3 oracle, real binary, local registry): L1 registry SSE / Streamable HTTP x vscode, copilot, claude, gemini, antigravity, codex at project and-g; legacytransport_type; missing transport; L3 self-defined SSE/HTTP incl. AntigravityserverUrland SSE warn/skip with later servers still configured; unchanged rows locked;apm mcp show;--frozenreplay of a refused registry SSE server (exit 0) and of a deferred pair that turns out supported (still exit 1,test_frozen_deferred_pair_that_turns_out_supported_is_refused), and a refused frozen replay leaves every native file byte-identical (test_refused_frozen_replay_changes_no_native_config).tests/integration/test_mcp_retired_shape_heal_lifecycle.py(RT3 oracle, real v0.35.1 and v0.36.0 fixtures): L2 heal via install/update/install --frozen x project/-g, foreign entry never taken over, policy interplay, cleanup after removal, stale Codex SSE removal,audit --cigreen, second install writes nothing.Fail-before evidence: the RT3 L1/L3 file fails 9 cases on v0.36.0; the frozen refused-SSE sequence returned rc 1 ("ownership is not recorded") before the fix. Mutation-breaking
_in_retired_shapeandmanaged_unsupported_connectionmakesheal[project-v0.36.0-install],heal[project-v0.35.1-install],codex-stale[v0.36.0-install],codex-stale[v0.35.1-install]and 4 unit heal cases fail.Validation commands (all run locally on the merged head):
uvx ruff@0.15.12 check src/ tests/ scripts/lint_architecture_boundaries.py scripts/architecture_linter/ scripts/windows_native_symlink_probe_entry.pyuvx ruff@0.15.12 format --check(same paths).venv/bin/python -m pylint --disable=all --enable=R0801 --min-similarity-lines=10 --fail-on=R0801 src/apm_cli/ scripts/lint_architecture_boundaries.py scripts/architecture_linter/ scripts/windows_native_symlink_probe_entry.pybash scripts/lint-auth-signals.shbash scripts/lint-architecture-boundaries.shpytest -p no:xdist tests/unit/adapters/test_mcp_remote_transport_shapes.py tests/unit/install/test_mcp_retired_shape_heal.py tests/unit/install/test_frozen_service_boundary.py tests/integration/test_architecture_owner_rule_mutations.pyAPM_E2E_TESTS=1 APM_BINARY_PATH=.venv/bin/apm pytest -p no:xdist tests/unit/install/test_frozen_service_boundary.py tests/integration/test_native_mcp_collision_lifecycle.py tests/integration/test_mcp_remote_transport_harness_lifecycle.pyAPM_E2E_TESTS=1 APM_BINARY_PATH=.venv/bin/apm pytest -p no:xdist tests/integration/test_mcp_retired_shape_heal_lifecycle.pypytest -p no:xdistover tests/unit MCP/registry/adapter/ownership/frozen files plus 19 MCP integration filesTestRemoveStale::test_opencode_requires_marker_directory,test_claude_project_cleanup_requires_marker_directory; both fail identically on v0.36.0)Spec conformance (OpenAPM v0.1)
docs/src/content/docs/specs/openapm-v0.1.mdupdated(new/changed
<a id="req-XXX"></a>anchor + prose + Appendix Crow).
docs/src/content/docs/specs/manifests/openapm-v0.1.requirements.ymlupdated.
@pytest.mark.req("req-XXX")test undertests/spec_conformance/added or extended.CONFORMANCE.{md,json}regenerated viauv run --extra dev python -m tests.spec_conformance.gen_statementand committed.
apm-spec-waiver:line.