fix(deps): subdir-agnostic bare cache fixes parallel sparse-checkout race (#1126)

CHANGELOG.md

@@ -7,6 +7,10 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+### Fixed
+
+- **Parallel subdir install race.** `apm install` no longer intermittently fails with `RuntimeError: Subdirectory '<path>' not found in repository` when multiple dependencies resolve to different subdirectories of the same `repo@ref`. The shared clone cache now stores subdir-agnostic bare clones and each consumer materializes its own working tree (mirrors the WS3 `GitCache` pattern). (#1135, fixes #1126)
+
 ## [0.12.1] - 2026-05-03
 
 ### Added

docs/src/content/docs/guides/dependencies.md

@@ -671,7 +671,7 @@ APM automatically retries failed HTTP requests with exponential backoff and jitt
 
 #### Parallel Downloads
 
-APM downloads packages in parallel using a thread pool, significantly reducing wall-clock time for large dependency trees. The concurrency level defaults to 4 and is configurable via `--parallel-downloads` (set to 0 to disable). For subdirectory packages in monorepos, APM attempts git sparse-checkout (git 2.25+) to download only the needed directory, falling back to a shallow clone if sparse-checkout is unavailable.
+APM downloads packages in parallel using a thread pool, significantly reducing wall-clock time for large dependency trees. The concurrency level defaults to 4 and is configurable via `--parallel-downloads` (set to 0 to disable). For sibling subdirectory packages from the same monorepo and ref (e.g. two skills under `skills/` in `github/awesome-copilot`), APM clones the repo bare exactly once into a shared cache and materializes each consumer's working tree from that cache via `git clone --local --shared --no-checkout`. This eliminates redundant network fetches and prevents the parallel races that affected earlier sparse-checkout based fetches.
 
 ### File Processing and Content Merging
 

scripts/test-integration.sh

@@ -388,7 +388,20 @@ run_e2e_tests() {
         log_error "APM Dependencies integration tests failed!"
         exit 1
     fi
-
+
+    # Subdirectory dedup race E2E (#1126): two sibling subdirs of the
+    # same upstream repo+ref must install in parallel without the
+    # "Subdirectory ... not found" race the v1 cache produced.
+    log_info "Running #1126 parallel subdir dedup E2E..."
+    echo "Command: pytest tests/integration/test_install_subdir_dedup_e2e.py -v -s --tb=short -m integration"
+
+    if pytest tests/integration/test_install_subdir_dedup_e2e.py -v -s --tb=short -m integration; then
+        log_success "#1126 subdir dedup E2E passed!"
+    else
+        log_error "#1126 subdir dedup E2E failed!"
+        exit 1
+    fi
+
     # Run Transport Selection integration tests (issue #778)
     # Always-on cases use HTTPS against a public repo. SSH cases auto-skip
     # when no usable SSH key is available for git@github.com.