Touch archives on hit and prune the cache store after restore

Record last use by touching the archive so the retention policy can
expire by access time, and run prune.sh after every restore (even on
miss) to keep the shared store trimmed: 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,26 @@ 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. Touches the archive on every hit, so the retention policy can expire by
+   last use
+
+## 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