Caution

Some comments are outside the diff and can’t be posted inline due to platform limitations.

.github/workflows/upgrade-pylib.md (1)

48-72: ⚠️ Potential issue | 🟠 Major

Stale cache after PYTHON_VERSION bump will silently use the wrong CPython source.

When PYTHON_VERSION is updated (e.g., v3.14.3 → v3.14.4), the exact cache key misses but restore-keys: cpython-lib- matches the previous version's cache. The cpython/Lib directory will exist from the old version, so the clone is skipped entirely — the agent silently operates on stale CPython sources.

Add a version check so the clone runs when the cached checkout doesn't match the desired tag:

🐛 Proposed fix: verify cached version matches

-if [ -d "cpython/Lib" ]; then
-    echo "CPython cache hit, skipping clone"
-else
-    git clone --depth 1 --branch "$PYTHON_VERSION" https://github.com/python/cpython.git cpython
-fi
+if [ -d "cpython/Lib" ] && git -C cpython describe --tags --exact-match 2>/dev/null | grep -qF "$PYTHON_VERSION"; then
+    echo "CPython cache hit for $PYTHON_VERSION, skipping clone"
+else
+    rm -rf cpython
+    git clone --depth 1 --branch "$PYTHON_VERSION" https://github.com/python/cpython.git cpython
+fi

Note: git describe --tags --exact-match may not work on a shallow clone without the tag fetched. An alternative is to persist the version in a marker file:

if [ -d "cpython/Lib" ] && [ "$(cat cpython/.cached_version 2>/dev/null)" = "$PYTHON_VERSION" ]; then
    echo "CPython cache hit for $PYTHON_VERSION, skipping clone"
else
    rm -rf cpython
    git clone --depth 1 --branch "$PYTHON_VERSION" https://github.com/python/cpython.git cpython
    echo "$PYTHON_VERSION" > cpython/.cached_version
fi