apm-cli 0.9.0__tar.gz → 0.9.2__tar.gz

{apm_cli-0.9.0/src/apm_cli.egg-info → apm_cli-0.9.2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: apm-cli
-Version: 0.9.0
+Version: 0.9.2
 Summary: MCP configuration tool
 Author-email: Daniel Meppiel <user@example.com>
 License: MIT License
@@ -70,6 +70,11 @@ GitHub Copilot · Claude Code · Cursor · OpenCode · Codex
 
 **[Documentation](https://microsoft.github.io/apm/)** · **[Quick Start](https://microsoft.github.io/apm/getting-started/quick-start/)** · **[CLI Reference](https://microsoft.github.io/apm/reference/cli-commands/)**
 
+---
+
+> **Portable by manifest. Secure by default. Governed by policy.**
+> One file describes every agent's context; one command reproduces it everywhere; one policy controls what an org will allow.
+
 ## Why APM
 
 AI coding agents need context to be useful — standards, prompts, skills, plugins — but today every developer sets this up manually. Nothing is portable nor reproducible. There's no manifest for it.
@@ -101,17 +106,37 @@ git clone <org/repo> && cd <repo>
 apm install    # every agent is configured
 ```
 
-## Highlights
+## The three promises
 
-- **[One manifest for everything](https://microsoft.github.io/apm/reference/primitive-types/)** — instructions, skills, prompts, agents, hooks, plugins, and [MCP servers](https://microsoft.github.io/apm/guides/mcp-servers/) declared in `apm.yml` and deployed across every client on install
+### 1. Portable by manifest
+
+One `apm.yml` describes every primitive your agents need — instructions, skills, prompts, agents, hooks, plugins, MCP servers — and `apm install` reproduces the exact same setup across every client on every machine. `apm.lock.yaml` pins the resolved tree the way `package-lock.json` does for npm.
+
+- **[One manifest for everything](https://microsoft.github.io/apm/reference/primitive-types/)** — declared once, deployed across Copilot, Claude, Cursor, OpenCode, Codex
 - **[Install from anywhere](https://microsoft.github.io/apm/guides/dependencies/)** — GitHub, GitLab, Bitbucket, Azure DevOps, GitHub Enterprise, any git host
 - **[Transitive dependencies](https://microsoft.github.io/apm/guides/dependencies/)** — packages can depend on packages; APM resolves the full tree
-- **[Content security](https://microsoft.github.io/apm/enterprise/security/)** — `apm audit` scans for hidden Unicode; `apm install` blocks compromised packages before agents read them
-- **[Author plugins](https://microsoft.github.io/apm/guides/plugins/)** — build Copilot, Claude, and Cursor plugins with dependency management and security scanning, then export standard `plugin.json`
-- **[Marketplaces](https://microsoft.github.io/apm/guides/marketplaces/)** — install plugins from curated registries in one command; deployed across all targets, locked, scanned, and [governed by `apm-policy.yaml`](https://microsoft.github.io/apm/enterprise/security/)
+- **[Author plugins](https://microsoft.github.io/apm/guides/plugins/)** — build Copilot, Claude, and Cursor plugins with dependency management, then export standard `plugin.json`
+- **[Marketplaces](https://microsoft.github.io/apm/guides/marketplaces/)** — install plugins from curated registries in one command, deployed across all targets and locked
 - **[Pack & distribute](https://microsoft.github.io/apm/guides/pack-distribute/)** — `apm pack` bundles your configuration as a zipped package or a standalone plugin
 - **[CI/CD ready](https://github.com/microsoft/apm-action)** — GitHub Action for automated workflows
 
+### 2. Secure by default
+
+Agent context is executable in effect — a prompt is a program for an LLM. APM treats it that way. Every install scans for hidden Unicode that can hijack agent behavior; the lockfile pins integrity hashes; transitive MCP servers are gated by trust prompts.
+
+- **[Content security](https://microsoft.github.io/apm/enterprise/security/)** — `apm install` blocks compromised packages before agents read them; `apm audit` runs the same checks on demand
+- **[Lockfile integrity](https://microsoft.github.io/apm/enterprise/governance/)** — `apm.lock` records resolved sources and content hashes for full provenance
+- **[MCP trust boundaries](https://microsoft.github.io/apm/guides/mcp-servers/)** — transitive MCP servers require explicit consent
+
+### 3. Governed by policy
+
+`apm-policy.yml` lets a security team say *"these are the only sources, scopes, and primitives this org will allow"* and have every `apm install` enforce it — with tighten-only inheritance from enterprise to org to repo, a published bypass contract, and audit-mode CI gates.
+
+- **[Governance Guide](https://microsoft.github.io/apm/enterprise/governance-guide/)** — the canonical enterprise reference: enforcement points, bypass contract, air-gapped story, failure semantics, rollout playbook
+- **[Policy reference](https://microsoft.github.io/apm/enterprise/policy-reference/)** — every check, every field, every default
+- **[Adoption playbook](https://microsoft.github.io/apm/enterprise/adoption-playbook/)** — staged rollout from warn to block across hundreds of repos
+- **[GitHub rulesets integration](https://microsoft.github.io/apm/integrations/github-rulesets/)** — wire `apm audit --ci` into branch protection
+
 ## Get Started
 
 #### Linux / macOS

{apm_cli-0.9.0 → apm_cli-0.9.2}/README.md

@@ -8,6 +8,11 @@ GitHub Copilot · Claude Code · Cursor · OpenCode · Codex
 
 **[Documentation](https://microsoft.github.io/apm/)** · **[Quick Start](https://microsoft.github.io/apm/getting-started/quick-start/)** · **[CLI Reference](https://microsoft.github.io/apm/reference/cli-commands/)**
 
+---
+
+> **Portable by manifest. Secure by default. Governed by policy.**
+> One file describes every agent's context; one command reproduces it everywhere; one policy controls what an org will allow.
+
 ## Why APM
 
 AI coding agents need context to be useful — standards, prompts, skills, plugins — but today every developer sets this up manually. Nothing is portable nor reproducible. There's no manifest for it.
@@ -39,17 +44,37 @@ git clone <org/repo> && cd <repo>
 apm install    # every agent is configured
 ```
 
-## Highlights
+## The three promises
 
-- **[One manifest for everything](https://microsoft.github.io/apm/reference/primitive-types/)** — instructions, skills, prompts, agents, hooks, plugins, and [MCP servers](https://microsoft.github.io/apm/guides/mcp-servers/) declared in `apm.yml` and deployed across every client on install
+### 1. Portable by manifest
+
+One `apm.yml` describes every primitive your agents need — instructions, skills, prompts, agents, hooks, plugins, MCP servers — and `apm install` reproduces the exact same setup across every client on every machine. `apm.lock.yaml` pins the resolved tree the way `package-lock.json` does for npm.
+
+- **[One manifest for everything](https://microsoft.github.io/apm/reference/primitive-types/)** — declared once, deployed across Copilot, Claude, Cursor, OpenCode, Codex
 - **[Install from anywhere](https://microsoft.github.io/apm/guides/dependencies/)** — GitHub, GitLab, Bitbucket, Azure DevOps, GitHub Enterprise, any git host
 - **[Transitive dependencies](https://microsoft.github.io/apm/guides/dependencies/)** — packages can depend on packages; APM resolves the full tree
-- **[Content security](https://microsoft.github.io/apm/enterprise/security/)** — `apm audit` scans for hidden Unicode; `apm install` blocks compromised packages before agents read them
-- **[Author plugins](https://microsoft.github.io/apm/guides/plugins/)** — build Copilot, Claude, and Cursor plugins with dependency management and security scanning, then export standard `plugin.json`
-- **[Marketplaces](https://microsoft.github.io/apm/guides/marketplaces/)** — install plugins from curated registries in one command; deployed across all targets, locked, scanned, and [governed by `apm-policy.yaml`](https://microsoft.github.io/apm/enterprise/security/)
+- **[Author plugins](https://microsoft.github.io/apm/guides/plugins/)** — build Copilot, Claude, and Cursor plugins with dependency management, then export standard `plugin.json`
+- **[Marketplaces](https://microsoft.github.io/apm/guides/marketplaces/)** — install plugins from curated registries in one command, deployed across all targets and locked
 - **[Pack & distribute](https://microsoft.github.io/apm/guides/pack-distribute/)** — `apm pack` bundles your configuration as a zipped package or a standalone plugin
 - **[CI/CD ready](https://github.com/microsoft/apm-action)** — GitHub Action for automated workflows
 
+### 2. Secure by default
+
+Agent context is executable in effect — a prompt is a program for an LLM. APM treats it that way. Every install scans for hidden Unicode that can hijack agent behavior; the lockfile pins integrity hashes; transitive MCP servers are gated by trust prompts.
+
+- **[Content security](https://microsoft.github.io/apm/enterprise/security/)** — `apm install` blocks compromised packages before agents read them; `apm audit` runs the same checks on demand
+- **[Lockfile integrity](https://microsoft.github.io/apm/enterprise/governance/)** — `apm.lock` records resolved sources and content hashes for full provenance
+- **[MCP trust boundaries](https://microsoft.github.io/apm/guides/mcp-servers/)** — transitive MCP servers require explicit consent
+
+### 3. Governed by policy
+
+`apm-policy.yml` lets a security team say *"these are the only sources, scopes, and primitives this org will allow"* and have every `apm install` enforce it — with tighten-only inheritance from enterprise to org to repo, a published bypass contract, and audit-mode CI gates.
+
+- **[Governance Guide](https://microsoft.github.io/apm/enterprise/governance-guide/)** — the canonical enterprise reference: enforcement points, bypass contract, air-gapped story, failure semantics, rollout playbook
+- **[Policy reference](https://microsoft.github.io/apm/enterprise/policy-reference/)** — every check, every field, every default
+- **[Adoption playbook](https://microsoft.github.io/apm/enterprise/adoption-playbook/)** — staged rollout from warn to block across hundreds of repos
+- **[GitHub rulesets integration](https://microsoft.github.io/apm/integrations/github-rulesets/)** — wire `apm audit --ci` into branch protection
+
 ## Get Started
 
 #### Linux / macOS

{apm_cli-0.9.0 → apm_cli-0.9.2}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "apm-cli"
-version = "0.9.0"
+version = "0.9.2"
 description = "MCP configuration tool"
 readme = "README.md"
 requires-python = ">=3.10"

{apm_cli-0.9.0 → apm_cli-0.9.2}/src/apm_cli/cli.py

@@ -28,6 +28,7 @@ from apm_cli.commands.marketplace import marketplace, search as marketplace_sear
 from apm_cli.commands.mcp import mcp
 from apm_cli.commands.outdated import outdated as outdated_cmd
 from apm_cli.commands.pack import pack_cmd, unpack_cmd
+from apm_cli.commands.policy import policy
 from apm_cli.commands.prune import prune
 from apm_cli.commands.run import preview, run
 from apm_cli.commands.runtime import runtime
@@ -82,6 +83,7 @@ cli.add_command(list_cmd, name="list")
 cli.add_command(config)
 cli.add_command(runtime)
 cli.add_command(mcp)
+cli.add_command(policy)
 cli.add_command(outdated_cmd, name="outdated")
 cli.add_command(marketplace)
 cli.add_command(marketplace_search, name="search")

{apm_cli-0.9.0 → apm_cli-0.9.2}/src/apm_cli/commands/audit.py

@@ -447,6 +447,15 @@ def _render_ci_results(ci_result: "CIAuditResult") -> None:
     is_flag=True,
     help="Force fresh policy fetch (skip cache).",
 )
+@click.option(
+    "--no-policy",
+    "no_policy",
+    is_flag=True,
+    help=(
+        "Skip org policy discovery and enforcement. "
+        "Overridden when --policy is passed explicitly."
+    ),
+)
 @click.option(
     "--no-fail-fast",
     "no_fail_fast",
@@ -454,7 +463,7 @@ def _render_ci_results(ci_result: "CIAuditResult") -> None:
     help="Run all checks even after a failure (default: stop at first failure).",
 )
 @click.pass_context
-def audit(ctx, package, file_path, strip, verbose, dry_run, output_format, output_path, ci, policy_source, no_cache, no_fail_fast):
+def audit(ctx, package, file_path, strip, verbose, dry_run, output_format, output_path, ci, policy_source, no_cache, no_policy, no_fail_fast):
     """Scan deployed prompt files for hidden Unicode characters.
 
     Detects invisible characters that could embed hidden instructions in
@@ -512,45 +521,81 @@ def audit(ctx, package, file_path, strip, verbose, dry_run, output_format, outpu
         # Always run baseline checks
         ci_result = run_baseline_checks(project_root, fail_fast=fail_fast)
 
-        # Optionally run policy checks (skip if baseline already failed in fail-fast mode)
-        if policy_source and (not fail_fast or ci_result.passed):
-            from ..policy.discovery import discover_policy
+        # Resolve policy source: explicit --policy wins; otherwise mirror
+        # install's auto-discovery (closes #827) so CI catches sideloaded
+        # files via unmanaged-files checks. --no-policy skips discovery.
+        from ..policy.discovery import discover_policy, discover_policy_with_chain
+        from ..policy.project_config import (
+            read_project_fetch_failure_default,
+        )
 
+        fetch_result = None
+        if policy_source and (not fail_fast or ci_result.passed):
             fetch_result = discover_policy(
                 project_root,
                 policy_override=policy_source,
                 no_cache=no_cache,
             )
+        elif (
+            not policy_source
+            and not no_policy
+            and (not fail_fast or ci_result.passed)
+        ):
+            # Auto-discovery (mirror install path)
+            fetch_result = discover_policy_with_chain(project_root)
+            # Treat outcomes that mean "no policy to enforce" as a no-op.
+            if fetch_result.outcome in ("absent", "no_git_remote", "empty", "disabled"):
+                fetch_result = None
+
+        if fetch_result is not None:
+            # Honor project-side fetch_failure_default when the org policy
+            # could not be fetched / parsed (closes #829). Default "warn"
+            # downgrades the previous unconditional sys.exit(1) into a log.
+            if fetch_result.error or (
+                fetch_result.outcome
+                in ("malformed", "cache_miss_fetch_fail", "garbage_response")
+            ):
+                project_default = read_project_fetch_failure_default(project_root)
+                err_text = fetch_result.error or fetch_result.fetch_error or fetch_result.outcome
+                if project_default == "block":
+                    logger.error(
+                        f"Policy fetch failed: {err_text} "
+                        "(policy.fetch_failure_default=block)"
+                    )
+                    sys.exit(1)
+                else:
+                    logger.warning(
+                        f"Policy fetch failed: {err_text}; "
+                        "proceeding without policy checks "
+                        "(set policy.fetch_failure_default=block in apm.yml to fail closed)"
+                    )
+                    fetch_result = None
 
-            if fetch_result.error:
-                logger.error(f"Policy fetch failed: {fetch_result.error}")
-                sys.exit(1)
+        if fetch_result is not None and fetch_result.found:
+            policy_obj = fetch_result.policy
 
-            if fetch_result.found:
-                policy_obj = fetch_result.policy
+            # Respect enforcement level
+            if policy_obj.enforcement == "off":
+                pass  # Policy checks disabled
+            else:
+                from ..policy.models import CheckResult
 
-                # Respect enforcement level
-                if policy_obj.enforcement == "off":
-                    pass  # Policy checks disabled
+                policy_result = run_policy_checks(
+                    project_root, policy_obj, fail_fast=fail_fast
+                )
+                if policy_obj.enforcement == "block":
+                    ci_result.checks.extend(policy_result.checks)
                 else:
-                    from ..policy.models import CheckResult
-
-                    policy_result = run_policy_checks(
-                        project_root, policy_obj, fail_fast=fail_fast
-                    )
-                    if policy_obj.enforcement == "block":
-                        ci_result.checks.extend(policy_result.checks)
-                    else:
-                        # enforcement == "warn": include results but don't fail
-                        for check in policy_result.checks:
-                            ci_result.checks.append(
-                                CheckResult(
-                                    name=check.name,
-                                    passed=True,  # downgrade to pass
-                                    message=check.message + (" (enforcement: warn)" if not check.passed else ""),
-                                    details=check.details,
-                                )
+                    # enforcement == "warn": include results but don't fail
+                    for check in policy_result.checks:
+                        ci_result.checks.append(
+                            CheckResult(
+                                name=check.name,
+                                passed=True,  # downgrade to pass
+                                message=check.message + (" (enforcement: warn)" if not check.passed else ""),
+                                details=check.details,
                             )
+                        )
 
         # Resolve effective format
         effective_format = output_format

{apm_cli-0.9.0 → apm_cli-0.9.2}/src/apm_cli/commands/install.py

@@ -1,6 +1,7 @@
 """APM install command and dependency installation engine."""
 
 import builtins
+import os
 import sys
 from pathlib import Path
 from typing import List, Optional
@@ -59,6 +60,7 @@ from apm_cli.install.phases.local_content import (
     _has_local_apm_content,
     _project_has_root_primitives,
 )
+from apm_cli.install.errors import PolicyViolationError
 from apm_cli.install.insecure_policy import (
     _InsecureDependencyInfo,
     _allow_insecure_host_callback,
@@ -86,6 +88,64 @@ from ._helpers import (
     _update_gitignore_for_apm_modules,
 )
 
+
+# ---------------------------------------------------------------------------
+# Manifest snapshot + rollback (W2-pkg-rollback, #827)
+# ---------------------------------------------------------------------------
+# When the user runs ``apm install <pkg>``, ``_validate_and_add_packages_to_apm_yml``
+# mutates ``apm.yml`` BEFORE the install pipeline runs.  If the pipeline fails
+# (policy block, download error, etc.) the failed package would stay in
+# ``apm.yml`` forever.  These helpers snapshot the raw bytes before mutation
+# and atomically restore on failure.
+# ---------------------------------------------------------------------------
+
+def _restore_manifest_from_snapshot(
+    manifest_path: "Path",
+    snapshot: bytes,
+) -> None:
+    """Atomically restore ``apm.yml`` from a raw-bytes snapshot.
+
+    Uses temp-file + ``os.replace`` to avoid torn writes, mirroring the
+    W1 cache atomic-write pattern (``discovery.py``).
+    """
+    import os
+    import tempfile
+
+    fd, tmp_name = tempfile.mkstemp(
+        prefix="apm-restore-", dir=str(manifest_path.parent),
+    )
+    try:
+        with os.fdopen(fd, "wb") as fh:
+            fh.write(snapshot)
+        os.replace(tmp_name, str(manifest_path))
+    except Exception:
+        try:
+            os.unlink(tmp_name)
+        except OSError:
+            pass
+        raise
+
+
+def _maybe_rollback_manifest(
+    manifest_path: "Path",
+    snapshot: "bytes | None",
+    logger: "InstallLogger",
+) -> None:
+    """Restore ``apm.yml`` from *snapshot* if one was captured, then log.
+
+    No-op when *snapshot* is ``None`` (i.e. the command was not
+    ``apm install <pkg>`` or the manifest did not exist before mutation).
+    """
+    if snapshot is None:
+        return
+    try:
+        _restore_manifest_from_snapshot(manifest_path, snapshot)
+        logger.progress("apm.yml restored to its previous state.")
+    except Exception:
+        # Best-effort: if the restore itself fails, warn but don't mask
+        # the original exception that triggered the rollback.
+        logger.warning("Failed to restore apm.yml to its previous state.")
+
 # CRITICAL: Shadow Python builtins that share names with Click commands
 set = builtins.set
 list = builtins.list
@@ -990,8 +1050,15 @@ def _run_mcp_install(
         "or a stdio command (self-defined entries)."
     ),
 )
+@click.option(
+    "--no-policy",
+    "no_policy",
+    is_flag=True,
+    default=False,
+    help="Skip org policy enforcement for this invocation. Loudly logged. Does NOT bypass apm audit --ci.",
+)
 @click.pass_context
-def install(ctx, packages, runtime, exclude, only, update, dry_run, force, verbose, trust_transitive_mcp, parallel_downloads, dev, target, allow_insecure, allow_insecure_hosts, global_, use_ssh, use_https, allow_protocol_fallback, mcp_name, transport, url, env_pairs, header_pairs, mcp_version, registry_url):
+def install(ctx, packages, runtime, exclude, only, update, dry_run, force, verbose, trust_transitive_mcp, parallel_downloads, dev, target, allow_insecure, allow_insecure_hosts, global_, use_ssh, use_https, allow_protocol_fallback, mcp_name, transport, url, env_pairs, header_pairs, mcp_version, registry_url, no_policy):
     """Install APM and MCP dependencies from apm.yml (like npm install).
 
     Detects AI runtimes from your apm.yml scripts and installs MCP servers for
@@ -1021,12 +1088,28 @@ def install(ctx, packages, runtime, exclude, only, update, dry_run, force, verbo
         apm install --mcp api --url https://example.com/mcp                   # remote http/sse
         apm install --mcp fetch -- npx -y @modelcontextprotocol/server-fetch  # stdio (post-- argv)
     """
+    # C1 #856: defaults BEFORE try so the finally clause never sees an
+    # UnboundLocalError if InstallLogger(...) raises during construction.
+    _apm_verbose_prev = os.environ.get("APM_VERBOSE")
     try:
         # Create structured logger for install output early so exception
         # handlers can always reference it (avoids UnboundLocalError if
         # scope initialisation below throws).
         is_partial = bool(packages)
         logger = InstallLogger(verbose=verbose, dry_run=dry_run, partial=is_partial)
+        # HACK(#852): surface --verbose to deeper auth layers via env var until
+        # AuthResolver gains a first-class verbose channel. Restored in finally
+        # below to keep the mutation scoped to this command invocation.
+        if verbose:
+            os.environ["APM_VERBOSE"] = "1"
+
+        # W2-pkg-rollback (#827): snapshot bytes captured BEFORE
+        # _validate_and_add_packages_to_apm_yml mutates apm.yml.
+        # Initialised to None here so exception handlers always have it.
+        _manifest_snapshot: "bytes | None" = None
+        # manifest_path is set later (scope-dependent); keep a stable ref
+        # so exception handlers can use it without NameError.
+        _snapshot_manifest_path: "Path | None" = None
 
         # ----------------------------------------------------------------
         # --mcp branch (W3): when --mcp is set, route to the dedicated
@@ -1088,6 +1171,43 @@ def install(ctx, packages, runtime, exclude, only, update, dry_run, force, verbo
             mcp_scope = InstallScope.PROJECT
             mcp_manifest_path = get_manifest_path(mcp_scope)
             mcp_apm_dir = get_apm_dir(mcp_scope)
+            # -- W2-mcp-preflight: policy enforcement before MCP install --
+            # Build a lightweight MCPDependency for policy evaluation.
+            # This mirrors _build_mcp_entry routing but we only need the
+            # fields that policy checks inspect (name, transport, registry).
+            from ..models.dependency.mcp import MCPDependency as _MCPDep
+            from ..policy.install_preflight import (
+                PolicyBlockError,
+                run_policy_preflight,
+            )
+
+            _is_self_defined = bool(url or command_argv)
+            _preflight_transport = transport
+            if _preflight_transport is None:
+                if command_argv:
+                    _preflight_transport = "stdio"
+                elif url:
+                    _preflight_transport = "http"
+            _preflight_dep = _MCPDep(
+                name=mcp_name,
+                transport=_preflight_transport,
+                registry=False if _is_self_defined else None,
+                url=url,
+            )
+
+            try:
+                _pf_result, _pf_active = run_policy_preflight(
+                    project_root=Path.cwd(),
+                    mcp_deps=[_preflight_dep],
+                    no_policy=no_policy,
+                    logger=logger,
+                    dry_run=dry_run,
+                )
+            except PolicyBlockError:
+                # Diagnostics already emitted by the helper + logger.
+                logger.render_summary()
+                sys.exit(1)
+
             if dry_run:
                 # C1: validate eagerly so dry-run rejects what real install would.
                 _validate_mcp_dry_run_entry(
@@ -1162,6 +1282,10 @@ def install(ctx, packages, runtime, exclude, only, update, dry_run, force, verbo
         # Create shared auth resolver for all downloads in this CLI invocation
         # to ensure credentials are cached and reused (prevents duplicate auth popups)
         auth_resolver = AuthResolver()
+        # F2/F3 #856: thread the InstallLogger into AuthResolver so the verbose
+        # auth-source line and the deferred stale-PAT [!] warning route through
+        # CommandLogger / DiagnosticCollector instead of stderr/inline writes.
+        auth_resolver.set_logger(logger)
 
         # Check if apm.yml exists
         apm_yml_exists = manifest_path.exists()
@@ -1186,6 +1310,15 @@ def install(ctx, packages, runtime, exclude, only, update, dry_run, force, verbo
 
         # If packages are specified, validate and add them to apm.yml first
         if packages:
+            # ── W2-pkg-rollback (#827): snapshot raw bytes BEFORE mutation ──
+            # _validate_and_add_packages_to_apm_yml does a YAML round-trip
+            # (load + dump) which may alter whitespace, key ordering, or
+            # trailing newlines.  We snapshot the raw bytes so rollback is
+            # byte-exact -- no YAML drift.
+            if manifest_path.exists():
+                _manifest_snapshot = manifest_path.read_bytes()
+                _snapshot_manifest_path = manifest_path
+
             validated_packages, outcome = _validate_and_add_packages_to_apm_yml(
                 packages, dry_run, dev=dev, logger=logger,
                 manifest_path=manifest_path, auth_resolver=auth_resolver,
@@ -1245,6 +1378,24 @@ def install(ctx, packages, runtime, exclude, only, update, dry_run, force, verbo
 
         # Show what will be installed if dry run
         if dry_run:
+            # -- W2-dry-run (#827): policy preflight in preview mode --
+            # Runs discovery + checks against direct manifest deps (not
+            # resolved/transitive -- dry-run does not run the resolver).
+            # Block-severity violations render as "Would be blocked by
+            # policy" without raising.  Documented limitation: transitive
+            # deps are NOT evaluated since the resolver does not run.
+            from apm_cli.policy.install_preflight import run_policy_preflight as _dr_preflight
+
+            _dr_apm_deps = builtins.list(apm_deps) + builtins.list(dev_apm_deps)
+            _dr_preflight(
+                project_root=project_root,
+                apm_deps=_dr_apm_deps,
+                mcp_deps=mcp_deps if should_install_mcp else None,
+                no_policy=no_policy,
+                logger=logger,
+                dry_run=True,
+            )
+
             from apm_cli.install.presentation.dry_run import render_and_exit
 
             render_and_exit(
@@ -1311,15 +1462,20 @@ def install(ctx, packages, runtime, exclude, only, update, dry_run, force, verbo
                     ),
                     protocol_pref=protocol_pref,
                     allow_protocol_fallback=allow_protocol_fallback,
+                    no_policy=no_policy,
                 )
                 apm_count = install_result.installed_count
                 prompt_count = install_result.prompts_integrated
                 agent_count = install_result.agents_integrated
                 apm_diagnostics = install_result.diagnostics
             except InsecureDependencyPolicyError:
+                _maybe_rollback_manifest(_snapshot_manifest_path, _manifest_snapshot, logger)
                 sys.exit(1)
             except Exception as e:
-                logger.error(f"Failed to install APM dependencies: {e}")
+                _maybe_rollback_manifest(_snapshot_manifest_path, _manifest_snapshot, logger)
+                # #832: surface PolicyViolationError verbatim (no double-nesting).
+                msg = str(e) if isinstance(e, PolicyViolationError) else f"Failed to install APM dependencies: {e}"
+                logger.error(msg)
                 if not verbose:
                     logger.progress("Run with --verbose for detailed diagnostics")
                 sys.exit(1)
@@ -1333,6 +1489,7 @@ def install(ctx, packages, runtime, exclude, only, update, dry_run, force, verbo
             clear_apm_yml_cache()
 
         # Collect transitive MCP dependencies from resolved APM packages
+        transitive_mcp = []
         apm_modules_path = get_modules_dir(scope)
         if should_install_mcp and apm_modules_path.exists():
             lock_path = get_lockfile_path(apm_dir)
@@ -1344,6 +1501,37 @@ def install(ctx, packages, runtime, exclude, only, update, dry_run, force, verbo
                 logger.verbose_detail(f"Collected {len(transitive_mcp)} transitive MCP dependency(ies)")
                 mcp_deps = MCPIntegrator.deduplicate(mcp_deps + transitive_mcp)
 
+        # -- S1/S2 fix (#827-C2/C3): enforce policy on ALL MCP deps ----
+        # The pipeline gate phase (policy_gate.py) checks direct APM deps
+        # and direct MCP deps from apm.yml.  However, transitive MCP
+        # servers (discovered via collect_transitive above) are only known
+        # after APM packages are installed.  Run a second preflight
+        # against the *merged* MCP set (direct + transitive) BEFORE
+        # MCPIntegrator writes runtime configs.  On PolicyBlockError we
+        # abort the MCP write but leave already-installed APM packages
+        # in place (they were approved by the gate phase).
+        if should_install_mcp and mcp_deps:
+            from apm_cli.policy.install_preflight import (
+                PolicyBlockError as _TransitivePBE,
+                run_policy_preflight as _transitive_preflight,
+            )
+
+            try:
+                _transitive_preflight(
+                    project_root=project_root,
+                    mcp_deps=mcp_deps,
+                    no_policy=no_policy,
+                    logger=logger,
+                    dry_run=False,
+                )
+            except _TransitivePBE:
+                logger.error(
+                    "MCP server(s) blocked by org policy. "
+                    "APM packages remain installed; MCP configs were NOT written."
+                )
+                logger.render_summary()
+                sys.exit(1)
+
         # Continue with MCP installation (existing logic)
         mcp_count = 0
         new_mcp_servers: builtins.set = builtins.set()
@@ -1407,16 +1595,24 @@ def install(ctx, packages, runtime, exclude, only, update, dry_run, force, verbo
             sys.exit(1)
 
     except InsecureDependencyPolicyError:
+        _maybe_rollback_manifest(_snapshot_manifest_path, _manifest_snapshot, logger)
         sys.exit(1)
     except click.UsageError:
         # Conflict matrix / argv parser raises UsageError -- let Click
         # render with exit code 2 and the standard "Usage: ..." prefix.
         raise
     except Exception as e:
+        _maybe_rollback_manifest(_snapshot_manifest_path, _manifest_snapshot, logger)
         logger.error(f"Error installing dependencies: {e}")
         if not verbose:
             logger.progress("Run with --verbose for detailed diagnostics")
         sys.exit(1)
+    finally:
+        # HACK(#852) cleanup: restore APM_VERBOSE so it stays scoped to this call.
+        if _apm_verbose_prev is None:
+            os.environ.pop("APM_VERBOSE", None)
+        else:
+            os.environ["APM_VERBOSE"] = _apm_verbose_prev
 
 
 # ---------------------------------------------------------------------------
@@ -1463,6 +1659,7 @@ def _install_apm_dependencies(
     marketplace_provenance: dict = None,
     protocol_pref=None,
     allow_protocol_fallback: "Optional[bool]" = None,
+    no_policy: bool = False,
 ):
     """Thin wrapper -- builds an :class:`InstallRequest` and delegates to
     :class:`apm_cli.install.service.InstallService`.
@@ -1494,5 +1691,6 @@ def _install_apm_dependencies(
         marketplace_provenance=marketplace_provenance,
         protocol_pref=protocol_pref,
         allow_protocol_fallback=allow_protocol_fallback,
+        no_policy=no_policy,
     )
     return InstallService().run(request)