fix(install): fail loudly when a package deploys to no target (closes #2796)

[Daniel Meppiel (danielmeppiel)]

Context: Agent Plugins v1.0.0 packages can only register natively with the copilot target today. When every selected target was non-copilot, apm install --skill ... --target codex skipped the package, deployed nothing, printed No changes, and exited 0.

WHY: A successful no-op hid an unsatisfied install request. The install outcome now fails only when target exclusion leaves the run with zero deployed packages, while mixed installs that deploy at least one package still exit 0.

BREAKING CHANGE: apm install now exits non-zero when Agent Plugin target exclusion means no package was deployed. Migration: install a direct skill subpath such as apm install kunchenguid/lavish-axi/skills/lavish#main --target codex, or select --target copilot for native Agent Plugin registration.

Scenario Evidence:

Scenario	Principle	Test path	Run evidence
Agent Plugin selected only for non-Copilot targets fails loudly, preserves the requested ref in the skill-subpath hint, and commits no durable state.	DevX; multi-harness support	tests/integration/test_required_lifecycle_state_machine.py::test_required_agent_plugin_target_exclusion_noop_fails_without_mutating_state	APM_E2E_TESTS=1 uv run --extra dev pytest tests/integration/test_required_lifecycle_state_machine.py::test_required_agent_plugin_target_exclusion_noop_fails_without_mutating_state -q -> 1 passed in 2.50s
Mixed installs stay successful when a target-excluded Agent Plugin deploys nothing but another package deploys.	DevX; multi-harness support	tests/unit/install/test_agent_plugin_deployment_boundary.py::test_target_exclusion_does_not_hard_fail_when_the_rest_of_the_batch_installs	uv run --extra dev pytest tests/unit/install/test_agent_plugin_deployment_boundary.py::test_target_exclusion_hint_names_remote_skill_subpath_form tests/unit/install/test_agent_plugin_deployment_boundary.py::test_target_exclusion_fails_when_no_package_is_deployed tests/unit/install/test_agent_plugin_deployment_boundary.py::test_target_exclusion_does_not_hard_fail_when_the_rest_of_the_batch_installs -q -> 10 passed in 2.44s

How to test:

• uv run --extra dev pytest tests/unit/install/test_agent_plugin_deployment_boundary.py::test_target_exclusion_hint_names_remote_skill_subpath_form tests/unit/install/test_agent_plugin_deployment_boundary.py::test_target_exclusion_fails_when_no_package_is_deployed tests/unit/install/test_agent_plugin_deployment_boundary.py::test_target_exclusion_does_not_hard_fail_when_the_rest_of_the_batch_installs -q
• uv run --extra dev pytest tests/unit/copilot_plugins/test_install_lifecycle.py -q
• APM_E2E_TESTS=1 uv run --extra dev pytest tests/integration/test_required_lifecycle_state_machine.py::test_required_agent_plugin_target_exclusion_noop_fails_without_mutating_state -q
• uv run --extra dev ruff check src/ tests/
• uv run --extra dev ruff format --check src/ tests/

Architecture: owner-extension. The deterministic owner-touch gate reports src/apm_cli/install/outcome.py under the canonical decision Install success / failure outcome; this PR extends that existing owner with the target-excluded no-deploy failure case while keeping per-package target exclusion detection in the Agent Plugin deployment boundary and diagnostics collector.

apm-spec-waiver: APM CLI-specific Agent Plugin target-exclusion UX; OpenAPM manifest and registry semantics are unchanged.

closes #2796

[Copilot]

Copilot review overview

🟢 Approval recommended

The changes correctly implement the specified failure condition with targeted diagnostics and comprehensive unit coverage for the new behavior (pure no-op, mixed batch, and dry-run).

Review tier: Lite
Findings: None

What changed in this PR

This PR updates the apm install outcome logic so that an Agent Plugins v1.0.0 package that is excluded by target selection (i.e., no selected target can receive it) is no longer treated as a successful no-op. Instead, the install fails (non-zero exit) only when that exclusion results in zero packages being deployed, matching the intent described in issue #2796.

Changes:

• Add a dedicated diagnostic subtype/count for “Agent Plugin target excluded” warnings and plumb it into install outcome classification.
• Update the install outcome owner to fail when installed_count == 0 and at least one Agent Plugin was target-excluded.
• Expand/adjust unit tests to cover: pure-no-op failure, mixed-batch non-fatal behavior, dry-run preview remaining non-fatal, and the actionable “install via /skills/” hint.

File	Description
tests/​unit/​install/​test_agent_plugin_deployment_boundary.py	Updates and adds regression tests for the new “fail loudly on pure no-op” behavior, including hint wording and dry-run parity.
src/​apm_cli/​utils/​diagnostics.py	Extends DiagnosticCollector.warn() with a severity subtype and adds a first-class Agent Plugin target-exclusion warning + counter.
src/​apm_cli/​install/​template.py	Builds an actionable skip message (including /skills/<skill> workaround) and records target exclusion using the new diagnostic subtype.
src/​apm_cli/​install/​outcome.py	Adds agent_plugin_target_excluded_count() helper and fails the install when exclusion caused a zero-deploy run.
CHANGELOG.md	Documents the breaking change and migration guidance under [Unreleased].

---

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