Save atomically and auto-prune the cache store

Write the archive to a .tmp file then rename into place so a concurrent
prune can never delete a half-written archive, and run prune.sh after
every save: keep the 3 newest archives per key-prefix family, expire
anything older than 7 days, hard-cap the store at 2 GB (oldest first,
trumping the keep set), never touch files younger than 1h, and drop
stale run workspaces under ~/.cache/act older than 2 days.

README.md

@@ -22,6 +22,25 @@ A Gitea Action that caches build files as `tar.xz` archives on the runner filesy
 1. Hashes `key-file` with SHA-256, combines with `key-prefix` as `<prefix>-<hash>`
 2. Stores archives at `~/.cache/.cache-store/<key>.tar.xz`
 3. Restores by extracting the archive to `/`, saves by creating one
+4. Saves atomically (write to `<key>.tar.xz.tmp`, then rename)
+
+## Cache Retention
+
+Archives are content-addressed, so old keys are never needed again — the store
+is pruned automatically on every restore/save (best-effort, safe under
+concurrent runners):
+
+- The newest `CACHE_KEEP_N` (default `3`) archives per key-prefix family are
+  always kept, so reverting e.g. `Cargo.lock` still hits an older key
+- Anything older than `CACHE_TTL_DAYS` (default `7`) outside the keep set is
+  deleted
+- A hard size cap `CACHE_CAP_GB` (default `2`) deletes oldest-first when
+  exceeded
+- Files younger than 1 hour are never touched (in-flight save protection)
+- Stale run workspaces under `~/.cache/act/*/hostexecutor` older than
+  `CACHE_WORKSPACE_TTL_DAYS` (default `2`) are removed
+
+Override the defaults per-job via `env:` (e.g. `env: { CACHE_KEEP_N: 5 }`).
 
 ## Usage