apm-cli 0.29.0__tar.gz → 0.30.0__tar.gz

{apm_cli-0.29.0/src/apm_cli.egg-info → apm_cli-0.30.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: apm-cli
-Version: 0.29.0
+Version: 0.30.0
 Summary: MCP configuration tool
 Author-email: Daniel Meppiel <user@example.com>
 License: MIT License
@@ -170,7 +170,16 @@ apm-policy.yml governs what gets installed; your agent harness governs what runs
 
 ## Get Started
 
-#### Linux / macOS
+#### macOS with Homebrew
+
+```bash
+brew install apm
+```
+
+No custom tap is required. Homebrew manages installation and updates:
+use `brew upgrade apm`, not `apm self-update`.
+
+#### Linux / macOS without Homebrew
 
 ```bash
 curl -sSL https://aka.ms/apm-unix | sh
@@ -182,17 +191,17 @@ curl -sSL https://aka.ms/apm-unix | sh
 irm https://aka.ms/apm-windows | iex
 ```
 
-Native release binaries are published for macOS, Linux, and Windows x86_64. `apm self-update` reuses the matching platform installer.
+Native release binaries are published for macOS, Linux, and Windows x86_64.
+For standalone installations, `apm self-update` reuses the matching platform installer.
+You do not need Homebrew to use APM.
 
 <details>
-<summary>Other install methods</summary>
+<summary>Other install methods: pip and Scoop</summary>
 
 #### Linux / macOS
 
 ```bash
-# Homebrew
-brew install microsoft/apm/apm
-# pip
+# pip (Python 3.10+)
 pip install apm-cli
 ```
 
@@ -208,6 +217,9 @@ pip install apm-cli
 
 </details>
 
+Already using the Microsoft Homebrew tap? See the
+[migration guide](https://microsoft.github.io/apm/getting-started/installation/#migrate-from-the-microsoft-tap).
+
 Then start adding packages:
 
 ```bash

{apm_cli-0.29.0 → apm_cli-0.30.0}/README.md

@@ -98,7 +98,16 @@ apm-policy.yml governs what gets installed; your agent harness governs what runs
 
 ## Get Started
 
-#### Linux / macOS
+#### macOS with Homebrew
+
+```bash
+brew install apm
+```
+
+No custom tap is required. Homebrew manages installation and updates:
+use `brew upgrade apm`, not `apm self-update`.
+
+#### Linux / macOS without Homebrew
 
 ```bash
 curl -sSL https://aka.ms/apm-unix | sh
@@ -110,17 +119,17 @@ curl -sSL https://aka.ms/apm-unix | sh
 irm https://aka.ms/apm-windows | iex
 ```
 
-Native release binaries are published for macOS, Linux, and Windows x86_64. `apm self-update` reuses the matching platform installer.
+Native release binaries are published for macOS, Linux, and Windows x86_64.
+For standalone installations, `apm self-update` reuses the matching platform installer.
+You do not need Homebrew to use APM.
 
 <details>
-<summary>Other install methods</summary>
+<summary>Other install methods: pip and Scoop</summary>
 
 #### Linux / macOS
 
 ```bash
-# Homebrew
-brew install microsoft/apm/apm
-# pip
+# pip (Python 3.10+)
 pip install apm-cli
 ```
 
@@ -136,6 +145,9 @@ pip install apm-cli
 
 </details>
 
+Already using the Microsoft Homebrew tap? See the
+[migration guide](https://microsoft.github.io/apm/getting-started/installation/#migrate-from-the-microsoft-tap).
+
 Then start adding packages:
 
 ```bash

{apm_cli-0.29.0 → apm_cli-0.30.0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "apm-cli"
-version = "0.29.0"
+version = "0.30.0"
 description = "MCP configuration tool"
 readme = "README.md"
 requires-python = ">=3.10"
@@ -219,4 +219,5 @@ markers = [
     "req: binds a test to one or more OpenAPM req-XXX ids (spec-conformance suite)",
     "lifecycle_smoke: promoted to the required PR-time Lifecycle Smoke (Linux) job -- see ci.yml's lifecycle-smoke job and docs/src/content/docs/contributing/integration-testing.md",
     "lifecycle_merge_group: unique lifecycle contracts retained in the full merge-group integration suite",
+    "xdist_group(name): assigns HOME-mutating tests to one pytest-xdist loadgroup for process-level serialization",
 ]

{apm_cli-0.29.0 → apm_cli-0.30.0}/src/apm_cli/adapters/client/base.py

@@ -7,7 +7,7 @@ from dataclasses import dataclass
 from pathlib import Path
 from typing import Any, ClassVar
 
-from ...models.dependency.mcp import _RESERVED_EXTRA_KEYS, TrustedEnvLiteral
+from ...models.dependency.mcp import _EXTRA_DENYLIST, TrustedEnvLiteral
 from ...utils.console import _rich_error, _rich_warning
 
 _INPUT_VAR_RE = re.compile(r"\$\{input:([^}]+)\}")
@@ -185,9 +185,6 @@ def _docker_image_repository(reference: str) -> str:
 # not be injectable via passthrough. Enforced unconditionally per adapter path
 # (NOT guarded by "key absent from config"), so it also closes paths that do not
 # pre-set the key. Security boundary for PR #1765 / issue #1670.
-_EXTRA_DENYLIST = _RESERVED_EXTRA_KEYS | frozenset({"http_headers"})
-
-
 @dataclass(frozen=True)
 class _MCPLauncherArgumentGroup:
     """One atomic registry argument and its rendered argv values."""

{apm_cli-0.29.0 → apm_cli-0.30.0}/src/apm_cli/adapters/client/codex.py

@@ -42,8 +42,9 @@ class CodexClientAdapter(MCPClientAdapter):
 
         Args:
             registry_url (str, optional): URL of the MCP registry.
-                If not provided, uses the MCP_REGISTRY_URL environment variable
-                or falls back to the default GitHub registry.
+                If not provided, resolves the MCP_REGISTRY_URL env var,
+                then ``apm config set mcp-registry-url``, then the public
+                default (see ``registry.client.resolve_mcp_registry_url``).
             project_root: Project root used to resolve project-local Codex
                 config paths.
             user_scope: Whether the adapter should resolve user-scope Codex

{apm_cli-0.29.0 → apm_cli-0.30.0}/src/apm_cli/adapters/client/copilot.py

@@ -92,8 +92,9 @@ class CopilotClientAdapter(MCPClientAdapter):
 
         Args:
             registry_url (str, optional): URL of the MCP registry.
-                If not provided, uses the MCP_REGISTRY_URL environment variable
-                or falls back to the default GitHub registry.
+                If not provided, resolves the MCP_REGISTRY_URL env var,
+                then ``apm config set mcp-registry-url``, then the public
+                default (see ``registry.client.resolve_mcp_registry_url``).
             project_root: Project root context passed through to the base
                 adapter for scope-aware operations.
             user_scope: Whether the adapter should resolve user-scope config

{apm_cli-0.29.0 → apm_cli-0.30.0}/src/apm_cli/adapters/client/gemini.py

@@ -31,6 +31,7 @@ import logging
 import os
 from pathlib import Path
 
+from ...utils.atomic_io import atomic_write_text
 from ...utils.console import _rich_error, _rich_success
 from .copilot import CopilotClientAdapter
 
@@ -102,8 +103,11 @@ class GeminiClientAdapter(CopilotClientAdapter):
                 "Creating %s for %s user configuration", config_path.parent, self.target_name
             )
         config_path.parent.mkdir(parents=True, exist_ok=True)
-        with open(config_path, "w", encoding="utf-8") as f:
-            json.dump(current_config, f, indent=2)
+        atomic_write_text(
+            config_path,
+            json.dumps(current_config, indent=2),
+            new_file_mode=0o600,
+        )
         os.chmod(config_path, 0o600)
 
     def get_current_config(self):

{apm_cli-0.29.0 → apm_cli-0.30.0}/src/apm_cli/adapters/client/intellij.py

@@ -91,6 +91,74 @@ def _legacy_intellij_config_dir() -> Path | None:
     return root.joinpath(*_CONFIG_SUFFIX)
 
 
+def _strip_jsonc_comments(raw: str) -> str:
+    """Strip JSONC comments while preserving string contents and line layout."""
+    chars = list(raw)
+    in_string = False
+    escaped = False
+    i = 0
+    while i < len(chars):
+        ch = chars[i]
+        if in_string:
+            if escaped:
+                escaped = False
+            elif ch == "\\":
+                escaped = True
+            elif ch == '"':
+                in_string = False
+            i += 1
+            continue
+        if ch == '"':
+            in_string = True
+            i += 1
+            continue
+        if ch == "/" and i + 1 < len(chars) and chars[i + 1] == "/":
+            j = i
+            while j < len(chars) and chars[j] not in "\r\n":
+                chars[j] = " "
+                j += 1
+            i = j
+            continue
+        if ch == "/" and i + 1 < len(chars) and chars[i + 1] == "*":
+            end = raw.find("*/", i + 2)
+            if end == -1:
+                return raw
+            for j in range(i, end + 2):
+                if chars[j] not in "\r\n":
+                    chars[j] = " "
+            i = end + 2
+            continue
+        i += 1
+    return "".join(chars)
+
+
+def _strip_jsonc_trailing_commas(raw: str) -> str:
+    """Blank trailing commas outside strings so strict JSON parsing accepts JSONC."""
+    chars = list(raw)
+    in_string = False
+    escaped = False
+    for index, char in enumerate(chars):
+        if in_string:
+            if escaped:
+                escaped = False
+            elif char == "\\":
+                escaped = True
+            elif char == '"':
+                in_string = False
+            continue
+        if char == '"':
+            in_string = True
+            continue
+        if char != ",":
+            continue
+        next_index = index + 1
+        while next_index < len(chars) and chars[next_index].isspace():
+            next_index += 1
+        if next_index < len(chars) and chars[next_index] in "}]":
+            chars[index] = " "
+    return "".join(chars)
+
+
 def _config_without_servers(
     config: dict,
     names: set[str],
@@ -153,7 +221,7 @@ class IntelliJClientAdapter(CopilotClientAdapter):
                 "Check its permissions and UTF-8 encoding, then rerun apm install."
             ) from exc
         try:
-            config = json.loads(raw)
+            config = json.loads(_strip_jsonc_trailing_commas(_strip_jsonc_comments(raw)))
         except json.JSONDecodeError as exc:
             raise IntelliJConfigError(
                 f"JetBrains Copilot MCP config at '{path}' is malformed JSON ({exc}). "

{apm_cli-0.29.0 → apm_cli-0.30.0}/src/apm_cli/adapters/client/opencode.py

@@ -30,6 +30,7 @@ import json
 import os
 from pathlib import Path
 
+from ...models.dependency.mcp import _EXTRA_DENYLIST
 from .copilot import CopilotClientAdapter
 
 
@@ -153,4 +154,9 @@ class OpenCodeClientAdapter(CopilotClientAdapter):
         if env:
             entry["environment"] = dict(env)
 
+        translated_keys = _EXTRA_DENYLIST
+        for key, value in copilot_entry.items():
+            if key not in translated_keys and key not in entry:
+                entry[key] = value
+
         return entry

{apm_cli-0.29.0 → apm_cli-0.30.0}/src/apm_cli/adapters/client/vscode.py

@@ -49,8 +49,9 @@ class VSCodeClientAdapter(MCPClientAdapter):
 
         Args:
             registry_url (str, optional): URL of the MCP registry.
-                If not provided, uses the MCP_REGISTRY_URL environment variable
-                or falls back to the default demo registry.
+                If not provided, resolves the MCP_REGISTRY_URL env var,
+                then ``apm config set mcp-registry-url``, then the public
+                default (see ``registry.client.resolve_mcp_registry_url``).
             project_root: Project root used to resolve the repository-local
                 `.vscode/mcp.json` path.
             user_scope: Whether to resolve user-scope config paths instead of

{apm_cli-0.29.0 → apm_cli-0.30.0}/src/apm_cli/agent_plugins/loader.py

@@ -110,7 +110,7 @@ class _CandidateResolution:
 
 def detect_agent_plugin(package_root: Path) -> AgentPluginDetection | None:
     """Classify and interpret a native Agent Plugin from its exact root manifest."""
-    from ..bundle.local_bundle import PluginSchemaRoute, classify_plugin_manifest_schema
+    from ..install.primitive_classification import PluginSchemaRoute, classify_plugin_manifest
 
     manifest_path = package_root / "plugin.json"
     try:
@@ -124,8 +124,8 @@ def detect_agent_plugin(package_root: Path) -> AgentPluginDetection | None:
         return None
     document = dict(evidence.document)
     try:
-        route = classify_plugin_manifest_schema(document)
-        if route is PluginSchemaRoute.LEGACY:
+        classification = classify_plugin_manifest(document)
+        if classification.route is PluginSchemaRoute.LEGACY:
             return None
         schema_id = document["$schema"]
         loader = _VERSION_LOADERS[schema_id]
@@ -175,7 +175,7 @@ def reject_agent_plugin_legacy_normalization(package_root: Path) -> None:
 
 def admit_legacy_plugin_manifest(package_root: Path) -> dict[str, Any] | None:
     """Return one admissible schema-less legacy manifest or reject fallback."""
-    from ..bundle.local_bundle import PluginSchemaRoute, classify_plugin_manifest_schema
+    from ..install.primitive_classification import PluginSchemaRoute, classify_plugin_manifest
 
     try:
         evidence = _read_admissible_root_manifest(package_root)
@@ -186,12 +186,12 @@ def admit_legacy_plugin_manifest(package_root: Path) -> dict[str, Any] | None:
     if evidence is None:
         return None
     try:
-        route = classify_plugin_manifest_schema(evidence.document)
+        classification = classify_plugin_manifest(evidence.document)
     except AgentPluginError as exc:
         raise AgentPluginLegacyBoundaryError(
             f"Schema-bearing plugin.json cannot enter Claude plugin normalization: {exc}"
         ) from exc
-    if route is PluginSchemaRoute.AGENT_PLUGIN:
+    if classification.route is PluginSchemaRoute.AGENT_PLUGIN:
         raise AgentPluginLegacyBoundaryError(
             "Agent Plugin input must be interpreted by load_agent_plugin(), "
             "not Claude plugin normalization"

{apm_cli-0.29.0 → apm_cli-0.30.0}/src/apm_cli/bundle/agent_plugin_exporter.py

@@ -20,7 +20,11 @@ from ..agent_plugins import (
     load_agent_plugin,
     url_contains_literal_secret,
 )
-from ..deps.lockfile import LockFile, get_lockfile_path, migrate_lockfile_if_needed
+from ..deps.lockfile import (
+    LockFile,
+    resolve_lockfile_path_for_read,
+    resolve_reproducible_timestamp,
+)
 from ..deps.plugin_parser import synthesize_plugin_json_from_apm_yml
 from ..models.apm_package import APMPackage
 from ..utils.archive import (
@@ -300,8 +304,7 @@ def export_agent_plugin_bundle(
     logger=None,
 ) -> PackResult:
     """Export the project as an Agent Plugin bundle."""
-    migrate_lockfile_if_needed(project_root)
-    lockfile_path = get_lockfile_path(project_root)
+    lockfile_path = resolve_lockfile_path_for_read(project_root, read_only=dry_run)
     lockfile = LockFile.read(lockfile_path)
     if lockfile is None:
         raise FileNotFoundError(
@@ -494,7 +497,7 @@ def export_agent_plugin_bundle(
             BundleFormat.AGENT_PLUGIN.lock_value,
             target or "all",
             bundle_files=bundle_files,
-            packed_at=lockfile.generated_at,
+            packed_at=resolve_reproducible_timestamp(None, lockfile.generated_at),
         )
         write_text_lf(staged_bundle / "apm.lock.yaml", enriched_yaml)
 

{apm_cli-0.29.0 → apm_cli-0.30.0}/src/apm_cli/bundle/local_bundle.py

@@ -29,22 +29,18 @@ import shutil
 import tempfile
 import zipfile
 from dataclasses import dataclass, field
-from enum import Enum
 from pathlib import Path
 from typing import TYPE_CHECKING, Any
 
 import yaml
 
-from ..agent_plugins.constants import (
-    AGENT_PLUGINS_SCHEMA_PREFIX,
-    COM_MICROSOFT_APM_NAMESPACE,
-    PLUGIN_SCHEMA_ID,
-)
-from ..agent_plugins.errors import (
-    AgentPluginManifestError,
-    UnsupportedAgentPluginVersionError,
-)
+from ..agent_plugins.constants import COM_MICROSOFT_APM_NAMESPACE
+from ..agent_plugins.errors import AgentPluginManifestError
 from ..agent_plugins.io import read_json_document
+from ..install.primitive_classification import (
+    PluginSchemaRoute,
+    classify_plugin_manifest_schema,
+)
 from ..utils.archive import (
     MAX_ZIP_ENTRIES,
     MAX_ZIP_UNCOMPRESSED,
@@ -61,48 +57,29 @@ from ..utils.yaml_io import load_yaml_str
 from .formats import BundleFormat
 
 if TYPE_CHECKING:
-    from collections.abc import Mapping
-
     from ..agent_plugins.ir import AgentPlugin, AgentPluginDetection
 
 _MAX_ZIP_ENTRIES = MAX_ZIP_ENTRIES
 _MAX_ZIP_UNCOMPRESSED = MAX_ZIP_UNCOMPRESSED
 
 
-class PluginSchemaRoute(Enum):
-    """Admission route selected exclusively by root plugin.json."""
-
-    LEGACY = "legacy"
-    AGENT_PLUGIN = "agent_plugin"
-
-
-def classify_plugin_manifest_schema(document: Mapping[str, Any]) -> PluginSchemaRoute:
-    """Select native admission only for the exact supported schema identifier."""
-    if "$schema" not in document:
-        return PluginSchemaRoute.LEGACY
-    schema_id = document["$schema"]
-    if not isinstance(schema_id, str):
-        raise AgentPluginManifestError("Invalid root plugin.json: $schema must be a string")
-    if schema_id == PLUGIN_SCHEMA_ID:
-        return PluginSchemaRoute.AGENT_PLUGIN
-    if schema_id.startswith(AGENT_PLUGINS_SCHEMA_PREFIX):
-        raise UnsupportedAgentPluginVersionError(
-            f"Unsupported Agent Plugins manifest schema: {schema_id}. "
-            f"This APM version supports only {PLUGIN_SCHEMA_ID}."
-        )
-    raise AgentPluginManifestError(
-        f"Unsupported schema-bearing plugin manifest: {schema_id}. "
-        f"APM accepts schema-bearing plugin.json only with {PLUGIN_SCHEMA_ID}; "
-        "remove $schema only for a schema-less legacy plugin."
-    )
-
-
 def route_agent_plugin_package(package_root: Path) -> AgentPluginDetection | None:
     """Route one materialized package through canonical Agent Plugin admission."""
     from ..agent_plugins.loader import detect_agent_plugin
+    from ..models.validation import PackageType, detect_package_type
 
     detection = detect_agent_plugin(package_root)
-    if detection is not None and detection.error is not None:
+    if detection is None:
+        return None
+    package_type, _ = detect_package_type(
+        package_root,
+        agent_plugin_detection=detection,
+    )
+    if package_type != PackageType.AGENT_PLUGIN:
+        if package_type == PackageType.INVALID and detection.error is not None:
+            raise detection.error
+        return None
+    if detection.error is not None:
         raise detection.error
     return detection
 

{apm_cli-0.29.0 → apm_cli-0.30.0}/src/apm_cli/bundle/packer.py

@@ -5,7 +5,7 @@ from dataclasses import dataclass, field
 from pathlib import Path
 
 from ..core.target_detection import detect_target
-from ..deps.lockfile import LockFile, get_lockfile_path, migrate_lockfile_if_needed
+from ..deps.lockfile import LockFile, resolve_lockfile_path_for_read
 from ..models.apm_package import APMPackage
 from ..utils.archive import (
     projected_archive_path,
@@ -67,8 +67,6 @@ def pack_bundle(
         FileNotFoundError: If ``apm.lock.yaml`` is missing.
         ValueError: If deployed files referenced in the lockfile are missing on disk.
     """
-    # 1. Read lockfile (migrate legacy apm.lock → apm.lock.yaml if needed)
-    migrate_lockfile_if_needed(project_root)
     bundle_format = coerce_bundle_format(fmt)
 
     if bundle_format is BundleFormat.AGENT_PLUGIN:
@@ -98,7 +96,7 @@ def pack_bundle(
             logger=logger,
         )
 
-    lockfile_path = get_lockfile_path(project_root)
+    lockfile_path = resolve_lockfile_path_for_read(project_root, read_only=dry_run)
     lockfile = LockFile.read(lockfile_path)
     if lockfile is None:
         raise FileNotFoundError(

{apm_cli-0.29.0 → apm_cli-0.30.0}/src/apm_cli/bundle/plugin_exporter.py

@@ -18,8 +18,7 @@ import yaml
 from ..deps.lockfile import (
     LockedDependency,
     LockFile,
-    get_lockfile_path,
-    migrate_lockfile_if_needed,
+    resolve_lockfile_path_for_read,
 )
 from ..models.apm_package import APMPackage, DependencyReference
 from ..models.dependency.subsets import skill_subset_filter_tokens
@@ -826,8 +825,7 @@ def export_plugin_bundle(
         :class:`PackResult` describing what was produced.
     """
     # 1. Read lockfile
-    migrate_lockfile_if_needed(project_root)
-    lockfile_path = get_lockfile_path(project_root)
+    lockfile_path = resolve_lockfile_path_for_read(project_root, read_only=dry_run)
     lockfile = LockFile.read(lockfile_path)
 
     # 2. Read apm.yml

apm_cli-0.30.0/src/apm_cli/bundle/plugin_layout.py

@@ -0,0 +1,60 @@
+"""Plugin-native source-layout conventions."""
+
+from collections.abc import Callable
+from dataclasses import dataclass
+from pathlib import Path
+
+
+def _identity(name: str) -> str:
+    """Return *name* unchanged."""
+    return name
+
+
+@dataclass(frozen=True)
+class PluginDirSpec:
+    """How one plugin-native root lowers into APM primitive space."""
+
+    plugin_dir: str
+    primitive_kinds: tuple[str, ...]
+    apm_basename_fn: Callable[[str], str]
+
+
+PLUGIN_ROOT_DIRS = (
+    "agents",
+    "skills",
+    "commands",
+    "instructions",
+    "extensions",
+    "hooks",
+)
+
+
+def find_plugin_root_sources(project_root: Path) -> list[str]:
+    """Return plugin-native root sources that exist."""
+    sources = [
+        name
+        for name in PLUGIN_ROOT_DIRS
+        if (project_root / name).is_dir() and not (project_root / name).is_symlink()
+    ]
+    if (project_root / "hooks.json").is_file():
+        sources.append("hooks.json")
+    return sources
+
+
+def plugin_command_prompt_name(name: str) -> str:
+    """Return the APM prompt filename represented by a plugin command."""
+    if name.endswith(".prompt.md"):
+        return name
+    if name.endswith(".md"):
+        return f"{name[: -len('.md')]}.prompt.md"
+    return name
+
+
+PLUGIN_LAYOUT: dict[str, PluginDirSpec] = {
+    "agents": PluginDirSpec("agents", ("agents",), _identity),
+    "skills": PluginDirSpec("skills", ("skills",), _identity),
+    "commands": PluginDirSpec("commands", ("commands", "prompts"), plugin_command_prompt_name),
+    "instructions": PluginDirSpec("instructions", ("instructions",), _identity),
+    "extensions": PluginDirSpec("extensions", ("canvas",), _identity),
+    "hooks": PluginDirSpec("hooks", ("hooks",), _identity),
+}

apm_cli-0.30.0/src/apm_cli/cache/cleanup.py

@@ -0,0 +1,51 @@
+"""Verified, best-effort removal outcomes for explicit cache cleaning."""
+
+from __future__ import annotations
+
+import os
+from collections.abc import Iterable
+from pathlib import Path
+
+from ..utils import file_ops
+
+
+def clean_cache_buckets(buckets: Iterable[Path]) -> list[str]:
+    """Remove bucket children without following links; return all failure details.
+
+    Successful removals are not rolled back. The residual check is essential:
+    the read-only recovery callback in robust_rmtree can swallow OS errors.
+    """
+    failures: list[str] = []
+    for bucket in buckets:
+        try:
+            if bucket.is_symlink():
+                failures.append(f"{bucket}: refusing to traverse a symlinked cache bucket")
+                continue
+            with os.scandir(bucket) as entries:
+                for entry in entries:
+                    path = Path(entry.path)
+                    try:
+                        if entry.is_dir(follow_symlinks=False):
+                            file_ops.robust_rmtree(path)
+                        else:
+                            path.unlink()
+                    except FileNotFoundError:
+                        pass
+                    except OSError as exc:
+                        failures.append(f"{path}: {exc}")
+                        continue
+                    try:
+                        # lstat distinguishes a removed entry from an unreadable
+                        # one and also detects dangling symlinks.
+                        path.lstat()
+                    except FileNotFoundError:
+                        continue
+                    except OSError as exc:
+                        failures.append(f"{path}: {exc}")
+                    else:
+                        failures.append(f"{path}: entry remains after deletion")
+        except FileNotFoundError:
+            continue
+        except OSError as exc:
+            failures.append(f"{bucket}: {exc}")
+    return failures