ci: fix stable cache misses (#13669)

### Summary
Fixes the stable extensions cache, which has been missing on every PR
and merge run since the 1.111 upstream merge.

- Path bug: `extensions/out` exists at save time but not restore time ->
excluded from the path list
- Key was non-deterministic across CI runs -> enumerate via `git
ls-tree` / `git ls-files` instead of filesystem `find`
- Key bumped v4 -> v7 to drop orphaned caches
- PRs restore from main; only test-merge.yml saves
- Cache hit/miss surfaced in the test/unit job summary

### QA Notes
First main run after merge populates the v7 cache.
We will now see a GH summary with cache hit/miss - instead of having to
dig through the job steps.

---------

Co-authored-by: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

Author: midleman

.github/actions/restore-build-caches/action.yml

@@ -37,6 +37,10 @@ inputs:
     description: "Whether to restore Playwright browsers cache (default: true)"
     required: false
     default: 'true'
+  emit-summary:
+    description: "Emit cache hit/miss summary to the job summary (default: false). Cache state is identical across jobs in a workflow, so opt in from one job to avoid duplication."
+    required: false
+    default: 'false'
 
 outputs:
   cache-npm-core-hit:
@@ -193,7 +197,7 @@ runs:
       uses: actions/cache/restore@v5
       with:
         path: ${{ steps.cache-paths.outputs.npm-extensions-stable-paths }}
-        key: npm-extensions-stable-v4-${{ runner.os }}-${{ steps.distro.outputs.distro }}-${{ steps.extensions-stable-hash.outputs.hash }}
+        key: npm-extensions-stable-v7-${{ runner.os }}-${{ steps.distro.outputs.distro }}-${{ steps.extensions-stable-hash.outputs.hash }}
 
     - name: Restore built-in extensions cache
       if: ${{ inputs.restore-builtins == 'true' }}
@@ -271,4 +275,7 @@ runs:
         CACHE_NPM_EXTENSIONS_STABLE_PARTIAL: ${{ steps.detect-partials.outputs.npm-extensions-stable-partial }}
         CACHE_BUILTINS_PARTIAL: ${{ steps.detect-partials.outputs.builtins-partial }}
         CACHE_PLAYWRIGHT_PARTIAL: ${{ steps.detect-partials.outputs.playwright-partial }}
+
+        # whether to write a summary block to $GITHUB_STEP_SUMMARY
+        EMIT_CACHE_SUMMARY: ${{ inputs.emit-summary }}
       run: .github/cache-scripts/log-cache-status.sh restore

.github/actions/save-build-caches/action.yml

@@ -129,7 +129,7 @@ runs:
       uses: actions/cache/save@v5
       with:
         path: ${{ steps.cache-paths.outputs.npm-extensions-stable-paths }}
-        key: npm-extensions-stable-v4-${{ runner.os }}-${{ steps.distro.outputs.distro }}-${{ inputs.extensions-stable-hash }}
+        key: npm-extensions-stable-v7-${{ runner.os }}-${{ steps.distro.outputs.distro }}-${{ inputs.extensions-stable-hash }}
 
     - name: Save built-in extensions cache
       if: ${{ inputs.cache-builtins-hit == 'false' }}

.github/cache-scripts/cache-paths.sh

@@ -155,14 +155,18 @@ generate_npm_extensions_stable_paths() {
 		fi
 	done <<< "$volatile_exts"
 
-	# Find all extensions except volatile ones and node_modules
+	# Find all extensions except volatile ones, node_modules, and build output.
+	# `out` is a build artifact directory (produced by esbuild-extension-common.mts).
+	# It only exists after compile, so including it would make the path list
+	# non-deterministic between cache restore (no out/) and cache save (out/ exists),
+	# producing different cache versions and constant misses.
 	local paths=""
 	for ext_dir in extensions/*/; do
 		ext_dir="${ext_dir%/}"
 		local ext_name="${ext_dir##*/}"
 
-		# Skip node_modules and volatile extensions
-		if [ "$ext_name" != "node_modules" ] && ! echo "$ext_name" | grep -qE "^($volatile_pattern)$"; then
+		# Skip node_modules, build output, and volatile extensions
+		if [ "$ext_name" != "node_modules" ] && [ "$ext_name" != "out" ] && ! echo "$ext_name" | grep -qE "^($volatile_pattern)$"; then
 			paths="${paths}${ext_dir}"$'\n'
 		fi
 	done

.github/cache-scripts/generate-extensions-hash.sh

@@ -119,8 +119,12 @@ if [ "$FILTER" == "volatile" ]; then
 	FILES_HASH=$(eval "find extensions .vscode -maxdepth 3 -name \"package.json\" -type f -not -path \"*/node_modules/*\" $FIND_EXCLUDES 2>/dev/null" | grep -E "($FILTER_PATTERN)" | sort | xargs cat 2>/dev/null | sha256sum | cut -d' ' -f1)
 elif [ "$FILTER" == "stable" ]; then
 	echo "  → Filtering: stable extensions only"
+	# Enumerate via git ls-files (deterministic) instead of find (filesystem-
+	# dependent). The find variant produced different hashes across runs of
+	# identical code, so the stable cache key never matched and the cache
+	# missed every run.
 	FILTER_PATTERN=$(IFS='|'; echo "${VOLATILE_EXTENSIONS[*]}")
-	FILES_HASH=$(eval "find extensions .vscode -maxdepth 3 -name \"package.json\" -type f -not -path \"*/node_modules/*\" $FIND_EXCLUDES 2>/dev/null" | grep -v -E "($FILTER_PATTERN)" | sort | xargs cat 2>/dev/null | sha256sum | cut -d' ' -f1)
+	FILES_HASH=$(git ls-files extensions .vscode | grep -E '(^|/)package\.json$' | grep -v '/node_modules/' | grep -v -E "($FILTER_PATTERN)" | sort | xargs cat 2>/dev/null | sha256sum | cut -d' ' -f1)
 else
 	echo "  → No filter: all extensions"
 	FILES_HASH=$(eval "find extensions .vscode -maxdepth 3 -name \"package.json\" -type f -not -path \"*/node_modules/*\" $FIND_EXCLUDES 2>/dev/null" | sort | xargs cat 2>/dev/null | sha256sum | cut -d' ' -f1)
@@ -151,9 +155,13 @@ if [ "$FILTER" == "volatile" ]; then
 	GIT_TREE_HASH=$(echo "$GIT_TREE_HASH" | sha256sum | cut -d' ' -f1)
 elif [ "$FILTER" == "stable" ]; then
 	echo "  → Filtering: stable extensions only"
-	ALL_EXT_DIRS=$(find extensions -maxdepth 1 -type d -not -name "node_modules" | tail -n +2 | sort)
+	# Enumerate via git ls-tree (deterministic) instead of find / bash glob
+	# (filesystem-dependent). `tree` covers regular subdirs; `commit` covers
+	# submodules (e.g. extensions/positron-copilot-chat).
+	ALL_EXT_DIRS=$(git ls-tree HEAD extensions/ | awk '$2=="tree" || $2=="commit" {print $4}' | sort)
 	GIT_TREE_HASH=""
-	for ext_dir in $ALL_EXT_DIRS; do
+	while IFS= read -r ext_dir; do
+		[ -z "$ext_dir" ] && continue
 		# Check if this is a volatile extension (skip if it is)
 		is_volatile=false
 		for volatile_ext in "${VOLATILE_EXTENSIONS[@]}"; do
@@ -167,16 +175,15 @@ elif [ "$FILTER" == "stable" ]; then
 			TREE_HASH=$(git rev-parse "HEAD:$ext_dir" 2>/dev/null || echo "no-tree")
 			GIT_TREE_HASH="${GIT_TREE_HASH}${TREE_HASH}"
 		fi
-	done
+	done <<< "$ALL_EXT_DIRS"
 
-	# Also hash .vscode/extensions/* (they're in the stable cache too!)
-	for vscode_ext_dir in .vscode/extensions/*/; do
-		if [ -d "$vscode_ext_dir" ]; then
-			vscode_ext_dir="${vscode_ext_dir%/}"
-			TREE_HASH=$(git rev-parse "HEAD:$vscode_ext_dir" 2>/dev/null || echo "no-tree")
-			GIT_TREE_HASH="${GIT_TREE_HASH}${TREE_HASH}"
-		fi
-	done
+	# Also hash .vscode/extensions/* (they're in the stable cache too).
+	VSCODE_EXT_DIRS=$(git ls-tree HEAD .vscode/extensions/ | awk '$2=="tree" || $2=="commit" {print $4}' | sort)
+	while IFS= read -r vscode_ext_dir; do
+		[ -z "$vscode_ext_dir" ] && continue
+		TREE_HASH=$(git rev-parse "HEAD:$vscode_ext_dir" 2>/dev/null || echo "no-tree")
+		GIT_TREE_HASH="${GIT_TREE_HASH}${TREE_HASH}"
+	done <<< "$VSCODE_EXT_DIRS"
 
 	GIT_TREE_HASH=$(echo "$GIT_TREE_HASH" | sha256sum | cut -d' ' -f1)
 else

.github/cache-scripts/log-cache-status.sh

@@ -145,3 +145,106 @@ elif [[ "$OPERATION" == "save" ]]; then
 	log_save_status "builtins"         "CACHE_BUILTINS_HIT"
 	log_save_status "playwright"       "CACHE_PLAYWRIGHT_HIT"
 fi
+
+# ============================================================================
+# SECTION 4: Job Summary (loud on miss, quiet on hit)
+# ============================================================================
+# Surface cache state in the GitHub Actions job summary so regressions are
+# visible without digging through raw logs. The stable cache miss bug went
+# undetected for 20+ days; this is the safety net.
+#
+# Hit case:     one terse line ("✅ All caches restored").
+# Miss case:    "## Cache" section with one bullet per cache showing state.
+# Skipped case: one terse line ("⏭️ All caches skipped") if no caches were enabled.
+#
+# Skipped if $GITHUB_STEP_SUMMARY is unset (local runs).
+
+# Only emit a summary for restore operations, and only when the caller opts in
+# via EMIT_CACHE_SUMMARY=true. Cache state is identical across jobs in a
+# workflow, so we opt in from one job (test/unit) to avoid duplication.
+# Save events are redundant with restore misses (a save only happens because
+# the matching restore missed), so we never emit a save summary.
+if [[ -z "${GITHUB_STEP_SUMMARY:-}" \
+	|| "$OPERATION" != "restore" \
+	|| "${EMIT_CACHE_SUMMARY:-false}" != "true" ]]; then
+	exit 0
+fi
+
+# Map a single cache to "hit" | "partial" | "miss" | "skipped".
+cache_state() {
+	local enabled_var="$1"
+	local hit_var="$2"
+	local partial_var="$3"
+
+	if [[ "${!enabled_var:-false}" != "true" ]]; then
+		echo "skipped"
+	elif [[ "${!hit_var:-false}" == "true" ]]; then
+		echo "hit"
+	elif [[ "${!partial_var:-false}" == "true" ]]; then
+		echo "partial"
+	else
+		echo "miss"
+	fi
+}
+
+# Render a cache state as a summary fragment.
+render_state() {
+	case "$1" in
+		hit)     echo "✅ hit" ;;
+		partial) echo "⚠️ partial" ;;
+		miss)    echo "❌" ;;
+		skipped) echo "⏭️ skipped" ;;
+		*)       echo "unknown" ;;
+	esac
+}
+
+# Cache definitions: name | enabled_var | hit_var | partial_var
+CACHES=(
+	"npm-core|RESTORE_NPM_CORE|CACHE_NPM_CORE_HIT|CACHE_NPM_CORE_PARTIAL"
+	"npm-ext-volatile|RESTORE_NPM_EXTENSIONS|CACHE_NPM_EXTENSIONS_VOLATILE_HIT|CACHE_NPM_EXTENSIONS_VOLATILE_PARTIAL"
+	"npm-ext-stable|RESTORE_NPM_EXTENSIONS|CACHE_NPM_EXTENSIONS_STABLE_HIT|CACHE_NPM_EXTENSIONS_STABLE_PARTIAL"
+	"builtins|RESTORE_BUILTINS|CACHE_BUILTINS_HIT|CACHE_BUILTINS_PARTIAL"
+	"playwright|RESTORE_PLAYWRIGHT|CACHE_PLAYWRIGHT_HIT|CACHE_PLAYWRIGHT_PARTIAL"
+)
+
+# Compute state per cache and count categories.
+states=()
+total=0
+exact_hits=0
+partial_hits=0
+misses=0
+for spec in "${CACHES[@]}"; do
+	IFS='|' read -r name enabled_var hit_var partial_var <<< "$spec"
+	state="$(cache_state "$enabled_var" "$hit_var" "$partial_var")"
+	states+=("$name|$state")
+
+	if [[ "$state" != "skipped" ]]; then
+		total=$((total + 1))
+	fi
+	case "$state" in
+		hit)     exact_hits=$((exact_hits + 1)) ;;
+		partial) partial_hits=$((partial_hits + 1)) ;;
+		miss)    misses=$((misses + 1)) ;;
+	esac
+done
+
+# Emit summary.
+{
+	if [[ "$total" -eq 0 ]]; then
+		echo "⏭️ All caches skipped"
+	elif [[ "$misses" -eq 0 ]]; then
+		if [[ "$partial_hits" -gt 0 ]]; then
+			echo "✅ All caches restored (${exact_hits} exact, ${partial_hits} partial)"
+		else
+			echo "✅ All caches restored (${exact_hits}/${total})"
+		fi
+	else
+		echo "## Cache"
+		echo ""
+		for entry in "${states[@]}"; do
+			IFS='|' read -r name state <<< "$entry"
+			echo "- ${name} $(render_state "$state")"
+		done
+	fi
+	echo ""
+} >> "$GITHUB_STEP_SUMMARY"

.github/workflows/test-pull-request.yml

@@ -286,7 +286,7 @@ jobs:
     uses: ./.github/workflows/test-unit.yml
     secrets: inherit
     with:
-      save_cache: true  # Only this job saves cache to avoid race conditions
+      save_cache: false  # PRs restore from main only; test-merge.yml saves
 
   ext-host-tests:
     name: test

.github/workflows/test-unit.yml

@@ -1,11 +1,14 @@
 name: "Test: Unit"
 
 # Cache Save Strategy:
-# This workflow has a save_cache parameter to prevent race conditions when multiple jobs
-# try to save the same cache key simultaneously. Only ONE job per calling workflow should
-# set save_cache: true. Examples:
-# - test-pull-request.yml: unit-tests saves, ext-host-tests and e2e do not
-# - test-merge.yml: unit-tests saves, setup/ext-host/e2e do not
+# Only main (test-merge.yml) saves caches; PRs restore from main only. This
+# avoids the 10 GB GitHub Actions cache ceiling getting thrashed by many
+# concurrent PRs each writing duplicate copies of identical content, which
+# previously caused mid-day evictions and effectively broke caching on main.
+# The save_cache parameter lets us scope the save step to the merge workflow.
+# Examples:
+# - test-pull-request.yml: save_cache=false (restore only)
+# - test-merge.yml: unit-tests sets save_cache=true (one saver per workflow run)
 # - test-full-suite.yml: only restores
 
 on:
@@ -57,6 +60,8 @@ jobs:
       - name: 📦 Restore caches
         id: restore-caches
         uses: ./.github/actions/restore-build-caches
+        with:
+          emit-summary: 'true'
 
       - name: Install system dependencies
         uses: ./.github/actions/install-system-deps