ci(cache): prune Actions cache entries nothing can restore

[gHashTag]

Part of #851 and #844. It works together with #852: that PR makes the chipdb cache able to hit, and this one makes room so the entry survives.

What was wrong

Live read of actions/caches on 2026-10-04:

• 161 entries, 10.73 GB, against a 10 GB limit.
• Almost all of them are setup-zig-cache-v2-*, which mlugg/setup-zig@v2 saves on every run of every Zig job, with the run id in the key.
• 100 entries sit on the merge refs of pull requests that are already closed: ci: a gate for steps that pipe a build into tee without pipefail #828, ci: every run script must parse -- two dispatch-only steps never could #839, fix(ci): a runs-on label glued from pieces may spell macos #840 and fix(ci): a self-hosted runner without a linux label may be a Mac #841. Only those pull requests could ever restore them.
• No chipdb entry is in the cache, so every FPGA job builds its chipdb from nothing (ci: chipdb cache never hits in 48 workflows (key carries github.run_id) #843).

What this adds

actions-cache-prune.yml runs hourly, when a pull request closes, and on demand. On demand it is a dry run by default. It deletes two kinds of entry:

1. Every entry on the merge ref of a closed pull request, or on a branch that no longer exists.
2. For keys that end in a run id, every entry except the newest of its series on the same ref. setup-zig restores by prefix, which takes the newest match, so the older entries are never read.

It keeps fixed keys (setup-zig-tarball-*, the chipdb keyed on part and image from #852) and the newest entry of each series on every live ref.

The rules live in .github/scripts/cache-prune.js. The job checks out the default branch, runs the rules' tests, and only then deletes anything. It does not use the closed pull request's merge ref, because that ref may already be gone and should not decide what gets deleted. actions-cache-prune-test.yml runs the same tests on any pull request that changes the rules.

Evidence

• Unit tests: 14 of 14 node --test cases pass. They cover:
  • series detection, including a part number that ends in digits;
  • closed and open pull requests, the same series on two refs, deleted branches, and equal timestamps;
  • a dry run that deletes nothing, and a real run that deletes exactly the planned set;
  • a 404 on delete is tolerated; a 403 fails the job;
  • a 500 on the branch lookup stops the run before any delete.
• Mutation tests: 12 of 12 mutants of the rules are killed. Each mutant flips one decision: closed pull requests kept, oldest kept, the series ignoring the ref, a dry run that deletes, and so on.
• Live dry run, read-only through gh api, against this repository on 2026-10-04: 161 entries, 10.73 GB. It would drop 139 (9.00 GB) and keep 22 (1.73 GB).
  • 100 of the dropped entries belong to closed pull requests ci: a gate for steps that pipe a build into tee without pipefail #828, ci: every run script must parse -- two dispatch-only steps never could #839, fix(ci): a runs-on label glued from pieces may spell macos #840 and fix(ci): a self-hosted runner without a linux label may be a Mac #841.
  • 39 are superseded setup-zig entries on main.
• actionlint is clean on both new workflows. The repository's run-syntax gate parses all 122 workflows on this branch, including both new ones.

Not measured

• The first real prune. A scheduled workflow only runs from the default branch, so nothing here deletes anything until this is merged. After the merge, gh workflow run actions-cache-prune.yml (a dry run by default) shows the plan before the first hourly run acts on it.
• Whether the hourly cadence is enough. It depends on how many Zig runs land in an hour. If the budget still fills between prunes, the next step is a workflow_run trigger after the Zig workflows.
• Per-job value of the setup-zig cache, the third item in ci: setup-zig caches fill the 10 GB Actions cache and evict every chipdb #844. It needs a hit measurement first, so ci: setup-zig caches fill the 10 GB Actions cache and evict every chipdb #844 stays open for it.

🤖 Generated with Claude Code

[github-actions]

X Brain Health Check

Score: 100.0/100
Status: 🟢 HEALTHY
Threshold: 80/100

X Brain is above merge threshold

[github-actions]

🧪 Brain Stress Test Results

Score: not measured (no stress test prints a Score: line)
Status: 🟢 PASS
Threshold: 270/300

X Stress test passed