aethersdr
diff --git a/‎.github/workflows/cache-cleanup.yml‎
Lines changed: 162 additions & 14 deletions b/‎.github/workflows/cache-cleanup.yml‎
Lines changed: 162 additions & 14 deletions
@@ -34,37 +34,43 @@ name: Cache cleanup
 # pins the repo at its allowance on its own, holding well under a day of caches
 # nothing will ever read.
 #
-# NOT handled here: caches on refs/pull/N/merge, which become unreadable when
-# the PR closes. A job for those was written and pulled back out before merge —
-# `pull_request` grants a read-only GITHUB_TOKEN for fork PRs and `permissions:`
-# cannot elevate it, so `gh cache delete` 403s; 22 of 25 open PRs are from
-# forks, so it would have failed on nearly every close. It also may not be
-# needed: PRs only WRITE a dependency cache (Qt, FFTW, DeepFilterNet) when the
-# key is not already readable, and the reason they were doing so is that main's
-# copy kept being evicted by the churn ci.yml's save-on-main split removes. Left
-# for a follow-up that can measure whether anything is still accumulating there,
-# and settle the trigger (a scheduled sweep avoids the privileged-trigger
-# question entirely).
+# The other cause is caches on refs/pull/N/merge, which become unreadable the
+# moment the PR closes — handled by sweep-closed-prs below, on a schedule rather
+# than on the close event. See that job for why the trigger is what it is.
 
 on:
   workflow_run:
     workflows: [CI]
     types: [completed]
+  # Daily, plus on demand. See sweep-closed-prs for why this is scheduled
+  # rather than fired from `pull_request: closed`.
+  schedule:
+    - cron: "17 4 * * *"
+  workflow_dispatch:
 
 # actions:write is the only elevated scope and it cannot reach anything outside
 # the cache API. It lives in this workflow rather than as a step in ci.yml
 # specifically so ci.yml keeps `contents: read` — nothing that compiles
 # PR-authored code ever holds a write scope.
 #
-# workflow_run runs in the BASE repository context with a full token even when
-# the run that triggered it came from a fork, which is why this job works where
-# a `pull_request`-triggered one would not.
+# pull-requests:read is a read scope, needed only by sweep-closed-prs to ask
+# whether a PR is still open. Listing it is not optional: naming ANY scope in a
+# `permissions:` block sets every unnamed one to `none`, and the job's lookup
+# would then fail on every ref while the job stayed green.
+#
+# All three triggers run in the BASE repository context with a full token:
+# workflow_run does so even when the run that triggered it came from a fork,
+# and schedule / workflow_dispatch only ever fire from the default branch. That
+# is why both jobs work where a `pull_request`-triggered one would not.
 permissions:
   actions: write
   contents: read
+  pull-requests: read
 
 jobs:
   prune-main:
+    # Only on a main push run — a scheduled or manual invocation is for the
+    # sweep below and has no new main entry to supersede anything.
     # workflow_run.event == 'push', NOT head_branch == 'main'. A fork's default
     # branch is usually also called main, so a head_branch test fires on fork PR
     # runs too — harmless in effect (the prune is idempotent and no fork run
@@ -163,3 +169,145 @@ jobs:
           gh api "repos/${{ github.repository }}/actions/cache/usage" \
             --jq '"Repo Actions cache: \(.active_caches_count) entries, \((.active_caches_size_in_bytes/1073741824)*100|floor/100) GiB of 10 GiB allowance"' \
             | tee -a "$GITHUB_STEP_SUMMARY"
+
+  # ── Dead cause 2: the PR closed ─────────────────────────────────────────────
+  # A PR's caches live on refs/pull/N/merge, a ref only that PR can read. Once it
+  # closes nothing can ever read them again, but they hold budget for up to the
+  # full 7-day retention.
+  #
+  # ci.yml's save-on-main split already stops PRs writing the big COMPILER
+  # caches. What still lands on a PR ref is a content-hash-keyed DEPENDENCY
+  # cache (Qt, FFTW3, DeepFilterNet3, qtkeychain, install-qt-action). In theory a
+  # PR only writes one when the key is not readable from main; in practice the
+  # repo sits at its allowance, LRU evicts main's copy between runs, and the
+  # next PR run re-saves its own — measured 2026-09-10: four open PRs each
+  # holding the same 1,297 MiB Qt entry main holds, plus a merged PR holding
+  # 1,720 MiB nothing could read. That loop is a ci.yml problem (the dependency
+  # caches want the same restore-on-PR / save-on-main split the compiler caches
+  # got); this job only reclaims the closed-PR leg of it.
+  #
+  # WHY SCHEDULED, not `pull_request: closed`
+  #
+  # The obvious trigger cannot work. For a `pull_request` event whose head is a
+  # fork, GitHub issues a read-only GITHUB_TOKEN and a `permissions:` block can
+  # only lower that ceiling, never raise it — so actions:write is not granted,
+  # `gh cache delete` returns 403, and the job fails. Most closed PRs here come
+  # from forks (44 of the last 60 on 2026-09-10), so that is the common case.
+  #
+  # `pull_request_target` would get a writable token and is the documented-safe
+  # shape for a job that checks nothing out. It is deliberately not used: a
+  # schedule needs no privileged trigger at all, is idempotent, and self-heals —
+  # it picks up PRs closed while the workflow was broken, renamed or disabled,
+  # which an event-driven job silently misses forever.
+  #
+  # The cost is latency: a closed PR's caches live until the next run, and while
+  # the repo is over its allowance they compete with main's live entries for LRU.
+  # If that bites, the sweep is idempotent and cheap enough to also hang off the
+  # workflow_run trigger above; the schedule then stays as the backstop.
+  #
+  # A PR that is closed and later REOPENED can read its ref again, but this job
+  # will already have deleted it; the reopened PR's first run re-saves its
+  # dependency caches (~1.7 GiB across platforms). Accepted, not a bug.
+  sweep-closed-prs:
+    if: github.event_name == 'schedule' || github.event_name == 'workflow_dispatch'
+    runs-on: ubuntu-latest
+    # A dispatch overlapping the cron would run two sweeps over the same refs;
+    # harmless to data but the two summaries would double-count. Queue instead.
+    concurrency:
+      group: cache-cleanup-sweep
+      cancel-in-progress: false
+    steps:
+      - name: Delete caches belonging to closed PRs
+        env:
+          GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+          GH_REPO: ${{ github.repository }}
+        run: |
+          set -euo pipefail
+
+          # gh paginates, so a high cap is free. It matters which end gets cut
+          # if the cap is ever hit: the default order is last-accessed first,
+          # and a closed PR's entries are by definition the least recently
+          # accessed, so a low cap would drop exactly the candidates. 36 entries
+          # on 2026-09-10 (usage API counts 23 active; the two endpoints differ),
+          # ~5 per open PR. Logged below if the cap is hit, because a silent
+          # truncation here would look exactly like "nothing to clean".
+          LIMIT=500
+          caches=$(gh cache list --limit "$LIMIT" --json id,ref,sizeInBytes)
+          total=$(printf '%s' "$caches" | jq 'length')
+          [ "$total" -lt "$LIMIT" ] || echo "::warning::cache list hit the $LIMIT limit; some entries not examined this run"
+
+          # Only refs/pull/N/merge entries are candidates. main and tag refs are
+          # not swept here: main's are handled by prune-main, and tag caches
+          # belong to release workflows that run rarely enough not to matter.
+          # One jq pass emits, per PR ref: number, total bytes, and the ids.
+          candidates=$(printf '%s' "$caches" | jq -r '
+            [.[] | select(.ref | test("^refs/pull/[0-9]+/merge$"))]
+            | group_by(.ref) | .[]
+            | "\(.[0].ref | capture("^refs/pull/(?<n>[0-9]+)/merge$").n)\t\(map(.sizeInBytes) | add)\t\(map(.id) | join(","))"')
+
+          if [ -z "$candidates" ]; then
+            echo "No PR-scoped caches at all — nothing to sweep."
+            exit 0
+          fi
+
+          freed=0
+          swept=0
+          unresolved=0
+          errlog="$RUNNER_TEMP/pr-view.err"
+          : > "$errlog"
+          while IFS=$'\t' read -r num bytes ids; do
+            mib=$(( bytes / 1048576 ))
+
+            # An OPEN PR's caches are still live — leave them. Anything else
+            # (CLOSED or MERGED) can never be read again.
+            state=$(gh pr view "$num" --json state --jq .state 2>>"$errlog" || echo UNKNOWN)
+            if [ "$state" = "OPEN" ]; then
+              continue
+            fi
+            if [ "$state" = "UNKNOWN" ]; then
+              # A cache ref with no resolvable PR. Left alone deliberately:
+              # deleting on a failed lookup would turn a transient API error
+              # into data loss, and the next run retries for free. Counted and
+              # surfaced below so a PERSISTENT cause (a missing scope, a rate
+              # limit) cannot hide behind the same message run after run.
+              echo "  #$num: state unresolved, skipping this run"
+              unresolved=$(( unresolved + 1 ))
+              continue
+            fi
+
+            echo "#$num ($state): sweeping ${mib} MiB"
+            # Delete by id, the same idiom as prune-main: unambiguous, and a
+            # single 404 (LRU took the entry between the list and now) neither
+            # aborts the loop nor counts toward `freed`.
+            ref_freed=0
+            for id in ${ids//,/ }; do
+              size=$(printf '%s' "$caches" | jq --argjson i "$id" '.[] | select(.id == $i) | .sizeInBytes')
+              if gh cache delete "$id"; then
+                ref_freed=$(( ref_freed + size ))
+              else
+                echo "  #$num: delete of $id failed or already gone"
+              fi
+            done
+            if [ "$ref_freed" -gt 0 ]; then
+              freed=$(( freed + ref_freed / 1048576 ))
+              swept=$(( swept + 1 ))
+            fi
+          done <<< "$candidates"
+
+          echo "Swept $swept closed PR(s), freeing ~${freed} MiB."
+          if [ "$unresolved" -gt 0 ]; then
+            echo "::warning::$unresolved PR state lookup(s) failed; their caches were left alone. gh stderr:"
+            cat "$errlog"
+          fi
+
+      # Same line prune-main prints, kept as a copy: a shared always() job was
+      # tried and rejected (see prune-main). If you change one, change both.
+      - name: Report repo cache usage
+        if: always()
+        env:
+          GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+        run: |
+          set -euo pipefail
+          gh api "repos/${{ github.repository }}/actions/cache/usage" \
+            --jq '"Repo Actions cache: \(.active_caches_count) entries, \((.active_caches_size_in_bytes/1073741824)*100|floor/100) GiB of 10 GiB allowance"' \
+            | tee -a "$GITHUB_STEP_SUMMARY"