Add known issue for osquery integration failure on macOS [#1528]

release-notes/fleet-elastic-agent/index.md

@@ -26,6 +26,18 @@ To check for security updates, go to [Security announcements for the Elastic sta
 % ### Fixes [fleet-elastic-agent-next-fixes]
 % *
 
+## 9.0.2 [fleet-elastic-agent-9.0.2-release-notes]
+
+### Features and enhancements [fleet-elastic-agent-9.0.2-features-enhancements]
+
+* Updates Go version to v1.24.3 in {{fleet}} [#4891]({{fleet-server-pull}}4891)
+
+* Updates Go version to v1.24.3 in {{agent}} [#8109]({{agent-pull}}8109)
+
+### Fixes [fleet-elastic-agent-9.0.2-fixes]
+
+* Improves the upgrade process for {{agent}} installed using DEB or RPM packages by copying the run directory from the previous installation into the new version's folder [#7999]({{agent-pull}}7999) [#3832]({{agent-issue}}3832)
+
 ## 9.0.1 [fleet-elastic-agent-9.0.1-release-notes]
 
 ### Features and enhancements [fleet-elastic-agent-9.0.1-features-enhancements]

release-notes/fleet-elastic-agent/known-issues.md

@@ -15,6 +15,63 @@ Known issues are significant defects or limitations that may impact your impleme
 % **Workaround** 
 % Workaround description.
 
-:::
+% :::
 
-_No known issues_
+:::{dropdown} [macOS] Osquery integration fails to start on fresh agent installs
+
+**Applies to: {{agent}} 9.0.0 and 9.0.1 (macOS only)**
+
+On May 26th, 2025, a known issue was discovered that causes the `osquery` integration to fail on new {{agent}} installations on macOS. During the installation process, the required `osquery.app/` directory is removed, which prevents the integration from starting.
+
+For more information, check [Issue #8245](https://github.com/elastic/elastic-agent/issues/8245).
+
+**Workaround** 
+
+As a workaround, you can manually restore the `osquery.app/` directory as follows:
+
+1. Extract the {{agent}} package, but do not install it yet.
+
+2. Open the following file in the extracted directory:
+
+   ```
+   data/elastic-agent-68f3ed/components/agentbeat.spec.yml
+   ```
+
+3. Locate the `component_files` section at the top of the file. It should look similar to this:
+
+   ```yaml
+   version: 2
+   component_files:
+     - certs/*
+     - lenses/*
+     - module/*
+     - "osquery-extension.ext"
+     - "osquery-extension.exe"
+     - osqueryd
+     - "osqueryd.exe"
+   ```
+
+4. Add the following entry to the end of the list:
+
+   ```yaml
+     - "osquery.app/*"
+   ```
+
+   The updated section should now look like this:
+
+   ```yaml
+   version: 2
+   component_files:
+     - certs/*
+     - lenses/*
+     - module/*
+     - "osquery-extension.ext"
+     - "osquery-extension.exe"
+     - osqueryd
+     - "osqueryd.exe"
+     - "osquery.app/*"
+   ```
+
+5. Proceed to install {{agent}} from the extracted directory as usual.
+
+:::