ci: fast, reliable dependency caching + concurrency fixes

- Cache the project .venv (primed once by cache-management, restored per job)
  so warm jobs skip 'uv sync' entirely; setup-uv's native wheel cache warms the
  cold prime.  Pin Python 3.12 before uv and set ORB_SKIP_UI_BUILD=1 so 'uv sync'
  never triggers the orb-py SPA build hook (reflex + bun), which otherwise hung
  jobs for >30 min.  Unify all callers on a single 'deps' cache-key base.
- Give push- and pull_request-triggered runs separate concurrency lanes
  (include github.event_name) so a push to a PR branch no longer has the two
  runs cancel each other and leave spurious CANCELLED required checks.

Author: fgogolli

.github/actions/setup-uv-cached/action.yml

@@ -1,33 +1,48 @@
 name: 'Setup UV with Cache'
-description: 'Install UV and restore cached environment'
+description: 'Install UV + restore the project venv; sync only on a cache miss'
 inputs:
   cache-key:
-    description: 'Cache key for UV environment'
+    description: 'Cache key for the .venv (from the caller''s setup-cache job).'
     required: true
   fail-on-cache-miss:
-    description: 'Whether to fail if cache is not found'
+    description: 'Fail if the .venv cache is not found.'
     required: false
-    default: 'true'
+    default: 'false'
 
 runs:
   using: 'composite'
   steps:
+    # Pin the interpreter BEFORE uv so uv never tries to fetch/build a Python.
+    - name: Set up Python
+      uses: actions/setup-python@ece7cb06caefa5fff74198d8649806c4678c61a1  # v6
+      with:
+        python-version: '3.12'
+
+    # setup-uv's native cache warms UV_CACHE_DIR (the wheel/download cache uv
+    # actually uses), keyed on uv.lock, so a cold sync links wheels instead of
+    # downloading them.
     - name: Install UV
       uses: astral-sh/setup-uv@11f9893b081a58869d3b5fccaea48c9e9e46f990  # v8.3.2
+      with:
+        version: "0.9.6"
+        enable-cache: true
+        cache-dependency-glob: "uv.lock"
 
-    - name: Restore UV environment
-      id: restore-cache
+    # Restore the fully-built .venv so a warm hit skips `uv sync` entirely.
+    - name: Restore project venv
+      id: restore-venv
       uses: actions/cache/restore@a7833574556fa59680c1b7cb190c1735db73ebf0  # v5.0.0
       with:
-        path: |
-          .venv
-          ~/.cache/uv
-          ~/.local/bin/uv
-          /opt/hostedtoolcache/uv
+        path: .venv
         key: ${{ inputs.cache-key }}
         fail-on-cache-miss: ${{ inputs.fail-on-cache-miss }}
 
-    - name: Install dependencies if cache miss
-      if: steps.restore-cache.outputs.cache-hit != 'true'
+    # Only sync on a .venv miss.  ORB_SKIP_UI_BUILD is CRITICAL: `uv sync` builds
+    # the orb-py package → setup.py build hook → build_ui.sh (reflex + bun) → a
+    # >30-min SPA build that times the job out.  These jobs don't need the SPA.
+    - name: Install dependencies (on venv cache miss)
+      if: steps.restore-venv.outputs.cache-hit != 'true'
       shell: bash
-      run: make dev-install
+      env:
+        ORB_SKIP_UI_BUILD: "1"
+      run: uv sync --frozen --all-groups

.github/actions/setup-uv-fresh/action.yml

@@ -12,7 +12,7 @@ on:
         required: true
         type: string
       cache-key-base:
-        description: 'Base cache key (e.g. test-deps, quality-deps)'
+        description: 'Base cache key — all callers must pass "deps" for the shared env'
         required: true
         type: string
       python-version:
@@ -22,11 +22,11 @@ on:
     outputs:
       cache-key:
         description: 'Generated cache key for use in setup-uv-cached'
-        value: ${{ jobs.generate-cache-key.outputs.cache-key }}
+        value: ${{ jobs.setup-cache.outputs.cache-key }}
 
 jobs:
-  generate-cache-key:
-    name: Generate Cache Key
+  setup-cache:
+    name: Prime Dependency Cache
     runs-on: ubuntu-latest
     permissions:
       contents: read
@@ -39,9 +39,18 @@ jobs:
     - name: Generate cache key
       id: cache-key
       run: |
+        # IMPORTANT: the key's python component must match the interpreter that
+        # setup-uv-cached (and this job) actually installs via actions/setup-python
+        # — currently '3.12' (hardcoded in both composites).  .project.yml
+        # default_version=3.14 is the *target* Python for release builds, but the
+        # CI venv is always 3.12.  Using inputs.python-version (=3.14) here would
+        # tag a 3.12 venv as 3.14, causing cache misses on every consumer job.
+        # When setup-uv-cached is updated to install a different Python, bump this
+        # literal to match.  See BUG-3 fix in feat/reflex-ui-conflict.
+        CACHE_PYTHON="3.12"
         case "${{ inputs.cache-type }}" in
           dependencies)
-            KEY="${{ inputs.cache-key-base }}-py${{ inputs.python-version }}-${{ hashFiles('.project.yml', 'pyproject.toml', 'uv.lock') }}"
+            KEY="${{ inputs.cache-key-base }}-py${CACHE_PYTHON}-${{ hashFiles('.project.yml', 'pyproject.toml', 'uv.lock') }}"
             ;;
           *)
             KEY="${{ inputs.cache-key-base }}-${{ github.sha }}"
@@ -50,16 +59,33 @@ jobs:
         echo "key=$KEY" >> "$GITHUB_OUTPUT"
         echo "Generated cache key: $KEY"
 
-    - name: Restore cache
-      id: cache
+    # Prime the .venv once so consumer jobs (setup-uv-cached, restore-only) hit a
+    # warm cache and skip `uv sync` entirely.  actions/cache saves at job end.
+    - name: Set up Python
+      uses: actions/setup-python@ece7cb06caefa5fff74198d8649806c4678c61a1  # v6
+      with:
+        python-version: '3.12'
+
+    - name: Cache project venv
+      id: venv-cache
       uses: actions/cache@55cc8345863c7cc4c66a329aec7e433d2d1c52a9  # v5
       with:
-        path: |
-          ~/.cache/uv
-          .venv
-          dist/
-          .pytest_cache
+        path: .venv
         key: ${{ steps.cache-key.outputs.key }}
-        restore-keys: |
-          ${{ inputs.cache-key-base }}-py${{ inputs.python-version }}-
-          ${{ inputs.cache-key-base }}-
+
+    - name: Install UV
+      if: steps.venv-cache.outputs.cache-hit != 'true'
+      uses: astral-sh/setup-uv@11f9893b081a58869d3b5fccaea48c9e9e46f990  # v8.3.2
+      with:
+        version: "0.9.6"
+        enable-cache: true
+        cache-dependency-glob: "uv.lock"
+
+    # ORB_SKIP_UI_BUILD: the sync builds orb-py → SPA build hook; skip it (the
+    # cached env doesn't need the compiled UI).
+    - name: Populate venv on cache miss
+      if: steps.venv-cache.outputs.cache-hit != 'true'
+      shell: bash
+      env:
+        ORB_SKIP_UI_BUILD: "1"
+      run: uv sync --frozen --all-groups

.github/workflows/cache-management.yml

@@ -32,7 +32,7 @@ jobs:
     uses: ./.github/workflows/cache-management.yml
     with:
       cache-type: dependencies
-      cache-key-base: changelog-validation
+      cache-key-base: deps
       python-version: ${{ needs.config.outputs.default-python-version }}
 
   validate-changelog:

.github/workflows/changelog-validation.yml

@@ -29,12 +29,19 @@ on:
 # (cancel-in-progress: false) because it pushes a commit back to the branch —
 # cancelling it mid-push could leave the branch in a partially formatted state.
 concurrency:
-  group: ci-${{ github.workflow }}-${{ github.ref }}
+  group: ci-${{ github.workflow }}-${{ github.ref }}-${{ github.event_name }}
   cancel-in-progress: true
 
 permissions:
   contents: read
 
+# ORB_SKIP_UI_BUILD is NOT set at workflow level here because every job either:
+#   (a) reaches uv sync via setup-uv-cached (which self-guards with
+#       ORB_SKIP_UI_BUILD: "1" at the composite step level), or
+#   (b) calls a make target with a dev-install prereq, which already exports
+#       ORB_SKIP_UI_BUILD=1 in the make recipe (makefiles/dev.mk:install).
+# A workflow-level env override is redundant and was removed for clarity.
+
 jobs:
   config:
     name: Configuration
@@ -46,7 +53,7 @@ jobs:
     uses: ./.github/workflows/cache-management.yml
     with:
       cache-type: dependencies
-      cache-key-base: quality-deps
+      cache-key-base: deps
       python-version: ${{ needs.config.outputs.default-python-version }}
 
   auto-format:

.github/workflows/ci-quality.yml

@@ -32,7 +32,7 @@ on:
 # Scheduled nightly runs use a stable group key so they never cancel each
 # other (there is only ever one running at a time by schedule).
 concurrency:
-  group: ci-${{ github.workflow }}-${{ github.ref }}
+  group: ci-${{ github.workflow }}-${{ github.ref }}-${{ github.event_name }}
   cancel-in-progress: true
 
 permissions:
@@ -49,7 +49,7 @@ jobs:
     uses: ./.github/workflows/cache-management.yml
     with:
       cache-type: dependencies
-      cache-key-base: test-deps
+      cache-key-base: deps
       python-version: ${{ needs.config.outputs.default-python-version }}
 
   # Parallel test-group matrix (T2613): splits the non-provider test corpus

.github/workflows/ci-tests.yml

@@ -32,7 +32,7 @@ jobs:
     uses: ./.github/workflows/cache-management.yml
     with:
       cache-type: dependencies
-      cache-key-base: dependabot
+      cache-key-base: deps
       python-version: ${{ needs.config.outputs.default-python-version }}
 
   update-uv-lock:

.github/workflows/dependabot.yml

@@ -4,15 +4,12 @@ env:
   CONTAINER_TRIGGERS: "/container"
 
 on:
-  push:
-    branches: [ main, develop ]
-    paths:
-      - 'Dockerfile*'
-      - 'src/**'
-      - 'pyproject.toml'
-      - 'deployment/docker/**'
-      - 'dev-tools/container/container_build.sh'
-      - '.github/workflows/dev-containers.yml'
+  # Deliberately no `push:` trigger.  On main pushes both a direct `push` event
+  # AND a `workflow_run` (after Unit Tests) would fire, both resolving to the
+  # same ref — per-ref concurrency (cancel-in-progress) would then cancel the
+  # first run, guaranteeing a CANCELLED result on every main push.
+  # Solution: rely on `workflow_run` alone for post-merge builds (consistent
+  # with dev-pypi and semantic-release which use the same pattern).
   workflow_run:
     workflows: ["Unit Tests"]
     types: [completed]
@@ -82,7 +79,7 @@ jobs:
       # fell through to the SHA-based fallback arm in cache-management.yml, producing
       # a cold key on every run and forcing a full dep reinstall each time.
       cache-type: dependencies
-      cache-key-base: container-build
+      cache-key-base: deps
       python-version: ${{ needs.config.outputs.default-python-version }}
 
   container-pipeline:

.github/workflows/dev-containers.yml

@@ -56,7 +56,7 @@ jobs:
     uses: ./.github/workflows/cache-management.yml
     with:
       cache-type: dependencies
-      cache-key-base: docs-deps
+      cache-key-base: deps
       python-version: ${{ needs.config.outputs.default-python-version }}
 
   build:

.github/workflows/docs.yml

@@ -26,8 +26,10 @@ env:
 # Per-ref concurrency: prevents a rapid series of pushes to main from queuing
 # redundant package-testing runs.  Each ref can only have one run active at a
 # time; a newer push cancels the older in-progress run.
+# github.event_name suffix prevents a push and pull_request on the same ref
+# from cancelling each other (matching the pattern in ci-tests.yml).
 concurrency:
-  group: ${{ github.workflow }}-${{ github.ref }}
+  group: ${{ github.workflow }}-${{ github.ref }}-${{ github.event_name }}
   cancel-in-progress: true
 
 jobs: