ci: Actions cache budget follow-ups after #5009 (dependency caches save on PR refs; sweep cadence; tag refs)

[ten9876]

Follow-ups from the review of #5009 (closed-PR cache sweep). None of these are needed for #5009 to merge; they track the parts of the cache-budget problem that PR deliberately does not solve.

Context (measured 2026-09-10)

PR-ref caches: 20 entries, 6881 MiB
repo usage:    23 entries, 9.88 GiB of 10 GiB

#5458 MERGED 1720 MiB   ← the only part #5009 can reclaim
#5462 OPEN    396 MiB
#5539 OPEN   1323 MiB
#5542 OPEN   1720 MiB
#5547 OPEN   1720 MiB

Four open PRs each hold their own copy of the same qt-6.8.3-macos-clang64-… (1,297 MiB) and install-qt-action-windows-… (396 MiB) keys that refs/heads/main also holds. PRs can read base-branch caches, so they should have restored; they wrote because the repo sits at its allowance, LRU evicts main's copy between runs, and the next PR run misses and re-saves. Main's Qt entry was re-created the same day, confirming it had been evicted again. Loop: PR writes → over quota → main's dependency entries evicted → more PR writes. #5009 trims the closed-PR leg only; with 4+ PRs open the repo stays over 10 GiB regardless.

1. Dependency caches: restore on PR, save only on main

The durable fix. #5008 gave the compiler caches (ccache-linux-build-, sccache-windows-, ccache-macos-ci) a restore-on-PR / save-on-main split. The dependency caches still use plain actions/cache and therefore save on PR refs whenever they miss:

• Cache Qt (ci.yml, qt-${QT_VERSION}-macos-clang64-…) — 1,297 MiB
• Cache FFTW3 (${runner.os}-fftw3-3.3.5-…)
• Cache DeepFilterNet3 (Linux / Windows / macOS jobs)
• Cache qtkeychain (qtkeychain-macos-arm64-…)

Switching each to actions/cache/restore + actions/cache/save with if: github.ref == 'refs/heads/main' means PR refs never hold dependency caches, main's copies stop being displaced, and the #5009 sweep has almost nothing to do.

Caveat: jurplel/install-qt-action with cache: true (Windows, 396 MiB per PR) has no restore-only mode. Either accept 396 MiB × open PRs, or move it to aqt + an explicit cache the way check-macos already does.

2. Should the sweep also run on workflow_run?

#5009 runs the sweep daily at 04:17 UTC. While the repo is over its allowance, a closed PR's dead entries compete with main's live ones for LRU until then; on a batch-merge afternoon that is several GiB of dead weight for up to a day, and GitHub's LRU ends up doing the sweep's job by also evicting main's compiler caches. The workflow_run: [CI] trigger already exists in cache-cleanup.yml with a full token (~35 fires/day). The sweep is idempotent and cheap (one list + one gh pr view per PR ref), so hanging it off that trigger too, with the schedule kept as the self-heal backstop, would cut dead time to minutes. Cost is ~35 short jobs/day. Decision, not a defect.

If #1 lands first, this mostly stops mattering.

3. Tag-ref caches

Caches on refs/tags/v* from the release workflows are swept by neither prune-main nor sweep-closed-prs. Low volume; recorded so it is not silently forgotten.

4. Record the usage-policy negative result

GET repos/aethersdr/AetherSDR/actions/cache/usage-policy returns 404 on this repo, so the per-repo size / retention policy is not exposed here. The cache-cleanup.yml header still invites investigating that route; a one-line note would save the next reader the trip.

Verification

gh cache list --limit 500 --json key,ref,sizeInBytes grouped by ref, after #1: no dependency keys on refs/pull/*/merge, and main's Qt / FFTW / DeepFilter / qtkeychain entries keep a stable createdAt across a week of PR runs.

Refs: #5008, #5009.

🤖 Generated with Claude Code

[aethersdr-agent]

Triaged: maintainer-review. I verified all four items against the tree at 981b7fe. The measurements and the mechanism hold up; two notes below where I think the issue understates something, and one where it overstates.

Standing caveat up front: #5009 is still open, so cache-cleanup.yml on main currently has only prune-main. Everything here is a follow-up to an unmerged PR — items 2 and 4 edit a job/header that doesn't exist on main yet, so they're blocked on #5009 landing. Item 1 and item 3 are independent of it.

1. Dependency caches save on PR refs — confirmed, and it's the right fix

Every step named is plain actions/cache (bidirectional), so a PR ref writes whenever it misses:

step	file	key
Cache DeepFilterNet3 (Linux)	ci.yml:133-138	deepfilter-${os}-${arch}-…
Cache FFTW3 (Windows)	ci.yml:302-306	${os}-fftw3-3.3.5-…
Cache DeepFilterNet3 (Windows)	ci.yml:312-317	deepfilter-…
Cache Qt (macOS)	ci.yml:574-579	qt-${QT_VERSION}-macos-clang64-aqt… — the 1,297 MiB one
Cache DeepFilterNet3 (macOS)	ci.yml:640-645	deepfilter-…
Cache qtkeychain (macOS)	ci.yml:651-658	qtkeychain-macos-arm64-…

Contrast with the three compiler caches, which #5008 (46ca499) already split: ci.yml:122-131/215-223 (Linux), 328-334/527-532 (Windows), 674-690 (macOS, via the action's own save: input). So this is finishing a migration that's already half-done in the same file, using a pattern the file already documents.

Two implementation details worth writing into the PR, because both are silent-failure shaped:

• Gate the save on the miss, not just the ref. These keys are content hashes, not run_id — unlike the compiler caches, where uniqueness is mandatory (ci.yml:220-222, 850-852). actions/cache/save against an already-present key warns rather than fails, so the save wants if: github.ref == 'refs/heads/main' && steps.<id>.outputs.cache-hit != 'true' to keep main's logs clean.
• The cache-hit gating on the setup steps keeps working. steps.cache-deepfilter.outputs.cache-hit etc. are set by actions/cache/restore too. These keys have no restore-keys, so exact-match is the only outcome and the semantics are unchanged — no need to touch ci.yml:140, 320, 648, 672.

Cost to accept explicitly: a PR that changes one of these keys — bumps QT_VERSION, edits setup-fftw.ps1, setup-deepfilter.sh, setup-qtkeychain.sh — misses on every push until it merges, because the entry only appears after the merge to main. For macOS Qt that's the ~6 min → ~18 min regression already measured at ci.yml:566-567. That's rare and self-limiting, and it's the correct trade against a permanent 1.3 GiB × N-open-PRs tax, but it should be a comment in the file rather than a surprise for whoever next bumps Qt.

The install-qt-action caveat is real (ci.yml:292-300, cache: true, no restore-only mode). Worth noting the escape hatch is already proven in-repo: check-macos does exactly the aqt + explicit-cache shape at ci.yml:574-600, so moving Windows to it is a port, not a design.

2. workflow_run for the sweep — agree it's mostly moot if #1 lands

The trigger does already exist (cache-cleanup.yml:52-55) with the full token, and the rationale for why that token works where pull_request doesn't is at cache-cleanup.yml:62-66. The sweep is idempotent, so the shape is sound. But note prune-main deliberately narrowed itself to ~9 of ~35 daily fires (cache-cleanup.yml:70-79) specifically to avoid spending runners on no-op invocations — adding an unfiltered job re-spends exactly what that comment saved. Since #1 removes the thing generating the dead weight, I'd land #1 first and only revisit this if usage is still pinned at the allowance afterward. Decision, as the issue says, not a defect.

3. Tag refs — understated; this is a permanent leak, not just low volume

This is the item I'd promote. appimage.yml, macos-dmg.yml and windows-installer.yml are all push: tags: ['v*'] only. A run on a tag ref can restore from its own ref or the default branch — and main never runs these workflows, so those keys exist only on tag refs. refs/tags/v26.9.1 therefore cannot read refs/tags/v26.9.0's entries. Every release writes a full set that no future run will ever read, and neither prune-main (scoped --ref refs/heads/main) nor #5009's sweep (scoped refs/pull/*) touches them.

Per release that's ~6 entries from windows-installer.yml:96-161 (Opus, FFTW3, hidapi, DeepFilterNet3, qtkeychain, Vulkan SDK) + macos-dmg.yml:178-236 (×2 matrix legs) + appimage.yml:222-227, each held for the full 7-day retention.

The sharpest instance: macos-dmg.yml:274-278 uses hendrikmuhs/ccache-action with key: ccache-macos-${{ matrix.label }}, no save: input, so append-timestamp defaults true and it writes a fresh uniquely-keyed 500 MB entry per release per matrix leg — the same superseded-entry accumulation prune-main exists to clean, on a ref prune-main doesn't look at and under a prefix (ccache-macos-) its PREFIXES list doesn't match (it has ccache-ccache-macos-ci-, cache-cleanup.yml:101-107). ~1 GB stranded per release. The fix is cheap: a third job, or extend the sweep's ref filter to refs/tags/* with a keep-newest-tag rule. Note cache-cleanup.yml:104-107 already states the rule this violates — "if you add a run_id-keyed compiler cache in ANY workflow, add it here."

4. usage-policy negative result — mostly already recorded

cache-cleanup.yml:10-17 already says retention is admin-managed, undocumented on this plan, and "the API does not expose it", and that the workflow assumes the default as a result. So the header doesn't really invite the trip — the remaining value is only naming the endpoint (GET repos/:owner/:repo/actions/cache/usage-policy) and its 404 so nobody re-runs the probe to confirm. That's a one-line addition to that existing paragraph, not a new note. Fold it into whichever PR touches the file next.

Handoff

• Do PHONE applet: DEXP commands rejected on firmware v1.4.0.0 #1. Six steps in ci.yml, mechanical, mirrors ci: restore compiler caches everywhere, save only on main #5008's existing pattern in the same file. Add the cache-hit != 'true' save gate and a comment about the key-change-in-PR cost. Decide separately on the install-qt-action → aqt port (396 MiB/PR); check-macos is the template.
• Do build(deps): Bump actions/checkout from 4 to 6 #3, sized as a real leak rather than a footnote — macos-dmg.yml:274-278 in particular.
• Defer build(deps): Bump github/codeql-action from 3 to 4 #2 until PHONE applet: DEXP commands rejected on firmware v1.4.0.0 #1's effect is measured.
• APD status indicators need refinement #4 is a one-line edit; no standalone PR.

Items 2 and 4 need #5009 merged first. Item 1 is the durable fix and stands alone — with it, the sweep in #5009 has almost nothing left to reclaim, which matches that PR's own framing.

---

_{🤖 aethersdr-agent · cost: $1.9400 · model: claude-opus-5}

---

_{📍 Citation health check (Foundry Constitution Principle I): 0 resolved, 22 unresolved against /Users/aetherclaude/workspace/AetherSDR at origin/main.}

Unresolved citations (22)

Citation	Reason
appimage.yml:222-227	file not found in workspace
cache-cleanup.yml:10-17	file not found in workspace
cache-cleanup.yml:101-107	file not found in workspace
cache-cleanup.yml:104-107	file not found in workspace
cache-cleanup.yml:52-55	file not found in workspace
cache-cleanup.yml:62-66	file not found in workspace
cache-cleanup.yml:70-79	file not found in workspace
ci.yml:122-131	file not found in workspace
ci.yml:133-138	file not found in workspace
ci.yml:140	file not found in workspace
ci.yml:220-222	file not found in workspace
ci.yml:292-300	file not found in workspace
ci.yml:302-306	file not found in workspace
ci.yml:312-317	file not found in workspace
ci.yml:566-567	file not found in workspace
ci.yml:574-579	file not found in workspace
ci.yml:574-600	file not found in workspace
ci.yml:640-645	file not found in workspace
ci.yml:651-658	file not found in workspace
macos-dmg.yml:178-236	file not found in workspace
macos-dmg.yml:274-278	file not found in workspace
windows-installer.yml:96-161	file not found in workspace

[ten9876]

5. Main-branch footprint: KEEP=2 and the Linux CCACHE_MAXSIZE put main alone over the allowance

Items 1–3 all reduce what PR and tag refs hold. They are needed, but they are not sufficient: refs/heads/main on its own is at the 10 GiB line once every compiler cache has filled to its cap, so the Linux ccache keeps being evicted even on days when PR refs hold nothing. This is the direct cause of the 30+ minute main builds (measured 2026-09-10).

The symptom

Every slow main run since 2026-09-06 is a cold build: the "Restore ccache objects" step completes in 0 s (GitHub found no ccache-linux-build-* entry), and the Build step goes from 3–6 min to 27–37 min. Runs with a restored cache are unchanged from before.

main runs	ccache restore	Build step
2026-09-05, typical	22–32 s	3–4 min
2026-09-06 04:23–04:41 (4 runs)	0–1 s	31–33 min
2026-09-06 16:10–16:21 (2 runs)	0–1 s	32–33 min
2026-09-07 19:51–20:07 (3 runs)	0 s	27–35 min
2026-09-10 15:56 (run 34498961117)	0 s	37 min

Run 34498961117's ccache --show-stats: 1901 / 2528 misses. Its restore log: Cache not found for input keys: ccache-linux-build-. prune-main had been skipped on every trigger between the previous main save (01:01) and that restore (15:57), so the prune did not delete it — GitHub's LRU eviction did, because the repo was over 10 GiB.

prune-main's own "Report repo cache usage" step has read between 9.2 and 10.8 GiB on every run since 2026-09-04.

Why main alone is over budget

The projection in ci.yml's CCACHE_MAXSIZE comment ("~5.1 to ~6.3 GiB") and the size table in cache-cleanup.yml's header were measured on 2026-08-15/16, while the compiler caches were still filling after #5008. They have since grown to their caps, and prune-main keeps two of each (KEEP: "2"). Steady state on refs/heads/main:

entry	cap	header's figure	now (2026-09-10)	×2 kept
ccache-linux-build-	2000M	~1.1 GiB	up to 2.0 GiB (661 MB right after a cold rebuild)	4.0 GiB
sccache-windows-	1G	~0.38 GiB	1.02 GiB	2.0 GiB
ccache-sid-canary-	1000M	~0.57 GiB	0.94 GiB	1.9 GiB
ccache-ccache-macos-ci-	500M	~0.18 GiB	0.44 GiB	0.9 GiB
Qt macOS + install-qt Windows + DeepFilter/FFTW/qtkeychain	—	—	~1.8 GiB	1.8 GiB
total				~10.6 GiB

That is over the allowance with zero entries on PR or tag refs. So after items 1–3 land, the eviction loop continues; it just has fewer bystanders. The Linux entry is the largest single compiler cache, which is why it is the one that goes (the Windows sccache-windows-34423038969 from the same run survived today's eviction; ccache-linux-build-34423038969 did not).

The context block at the top of this issue (main ≈ 3 GiB) was measured at a moment when main's Linux ccache had just been evicted, which is why it understates main's steady-state footprint.

Fixes

5a. KEEP: "2" → "1" in cache-cleanup.yml prune-main. Frees ~4.5 GiB on its own. The second copy is documented as insurance against a sparse/corrupt save, but (a) the success() gate on every save step already prevents the sparse case the comment describes, (b) that insurance has never been used in 25 days, and (c) it is currently costing far more than a corrupt-entry recovery would: a single evicted Linux entry costs ~30 min × every main run until the next green save, and the rebuilt entry starts from 661 MB instead of a warm ~2 GiB. If the insurance is wanted, keep it only for the Linux prefix; do not double the other three.

5b. Linux CCACHE_MAXSIZE: 2000M → 1000M in ci.yml. A full cold build of the whole tree produces a 661 MB cache (run 34498961117, 100% cacheable calls, 0.7 / 2.0 GB after the build). Everything above ~700 MB in a 2000M cache is stale objects from source that no longer exists, which restore/save then ship and LRU then evicts. 1000M holds a full build plus a comfortable margin and cuts the largest entry in half. (The 2000M was set in #5008 with the comment that entry COUNT, not size, was the binding constraint — true then, when PR refs held 8.6 GiB; not true once main's own entries are the budget.) The Windows and canary caps are already 1G and at steady state.

5c. Interim, no code: gh cache delete the superseded second copies and the duplicate PR-ref Qt entries by hand to get the Linux cache stable immediately, rather than waiting a week for retention. The next green main run re-saves a warm entry.

Verification

After 5a+5b: prune-main's usage line reads ≤ ~6 GiB with no open-PR caches (≤ ~8 GiB with item 1 not yet landed); "Restore ccache objects" on main is never 0 s across a week of pushes; Build step stays in the 3–6 min band; ccache --show-stats on main shows the hit rate climbing back above ~75% after the first warm save.

Ordering

5a and 5b are two one-line edits, independent of #5009 and of items 1–3, and are the only items here that stop the Linux cold builds by themselves. Land them first; they are also what makes the rest of this issue's "usage stays under the allowance" verification achievable.