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/workflows/cache-management.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
@@ -50,16 +50,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/changelog-validation.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/ci-quality.yml

@@ -29,12 +29,20 @@ 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
 
+# Every make target here (ci-quality-ruff, format-fix, pyright, arch checks)
+# has a `dev-install` prerequisite that runs `uv sync`, which builds the orb-py
+# package and fires setup.py's SPA build hook (reflex + bun) — a >15-min job
+# that times these steps out.  These jobs never need the compiled UI, so skip
+# the SPA build for the whole workflow.
+env:
+  ORB_SKIP_UI_BUILD: "1"
+
 jobs:
   config:
     name: Configuration
@@ -46,7 +54,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-tests.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/dependabot.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/dev-containers.yml

@@ -82,7 +82,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/docs.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/reusable-test.yml

@@ -92,6 +92,9 @@ env:
   AWS_SECRET_ACCESS_KEY: ${{ inputs.aws-secret-key }}
   ENVIRONMENT: ${{ inputs.environment }}
   TESTING: ${{ inputs.testing-flag }}
+  # Any make target that (re)runs uv sync would rebuild orb-py and fire the
+  # SPA build hook; test jobs never need the compiled UI, so skip it.
+  ORB_SKIP_UI_BUILD: "1"
 
 jobs:
   test:
@@ -116,7 +119,7 @@ jobs:
             ${{
               inputs.cache-key != ''
               && inputs.cache-key
-              || format('test-deps-py{0}-{1}',
+              || format('deps-py{0}-{1}',
                    inputs.python-version || inputs.default-python-version,
                    hashFiles('.project.yml', 'pyproject.toml', 'uv.lock'))
             }}

.github/workflows/test-matrix.yml

@@ -28,7 +28,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 }}
 
   unit-tests: