fix(shader-cache): remove stale temporary files from the cache root

[tibzejoker]

What

The shader cache's housekeeping removes *.tmp.* files older than one hour, but only in the current version subdirectory. The Vulkan pipeline cache (vk-pipelines-*.bin) is saved with WriteFileAtomically in the cache root, one level up. A run that stops while that file is being saved (killed, crashed, closed during the save) leaves its temporary file in the root, and nothing ever removes it.

For a large title the pipeline cache is big: here it is 2.5 GB, and three runs stopped during the save left 7.2 GB of vk-pipelines-*.bin.tmp.* files in shader_cache/. Housekeeping now applies the same one-hour rule to the root as well. Only regular files whose name contains .tmp. are removed; recent ones are kept because another run may still be writing them. USAGE.md now describes this.

Tested

Windows 11, MinGW GCC 15.2:

• New case in agc_shader_disk_cache (--housekeeping child process). The cache root holds a pipeline cache file, a temporary file two hours old, and a recent temporary file. A process looks up a shader there and shuts the cache down. The old temporary file must be gone; the other two must remain. On main it fails with a temporary file left in the cache root by an interrupted write survived housekeeping.
• ctest -R "agc_shader_disk_cache|agc_driver_graphics|agc_driver_pipeline|agc_driver_recorder|agc_driver_shutdown": 26/26.
• tools/check_conventions.py --base upstream/main: passed.
• Found in GTA V (PPSA04264): the files were left by test runs that were stopped while the game saved its pipeline cache.

Checklist

• Based on current main; no other open PR implements the same functions
• One topic per PR; follow-ups go in a new PR
• No comments in code except technical debt
• Unimplemented paths throw (NotImplemented_nid_no_patch); silent stubs are listed under Silent stubs in their library's technical debt file
• No notes, investigation .md files or images added to the repository (attach them to this PR)
• New third-party code is a submodule built from source
• Generic behaviour, not specific to one title
• Depends on: none
• Fixes: none
• Unblocks: none
• GPUs tested: n/a (file housekeeping; the test does not use the GPU)
• AI-assisted: yes (Claude Code)

🤖 Generated with Claude Code

https://claude.ai/code/session_01XBXM4pgkMHYEtqN1EQni2P

[github-actions]

Other open pull requests touch the same code. Merging one will break the other, or both implement the same thing. If this one builds on them, list them in Depends on.

Pull request	Conflicting files (lines on main)	Same exports	Same new files
PR 6771	docs/user/USAGE.md L281

Some comparisons could not be completed because a pull request conflicts with the base branch. Review these shared files manually before concluding that there is no overlap.

Pull request	Shared files not compared
PR 5021	docs/user/USAGE.md
PR 5500	core/shader/recompiler/ShaderDiskCache.cpp
PR 5609	core/libs/prx/libSceAgcDriver/tests/ShaderDiskCache.cpp core/shader/recompiler/ShaderDiskCache.cpp
PR 5656	core/libs/prx/libSceAgcDriver/tests/ShaderDiskCache.cpp core/shader/recompiler/ShaderDiskCache.cpp
PR 5925	core/shader/recompiler/ShaderDiskCache.cpp docs/user/USAGE.md
PR 6177	core/libs/prx/libSceAgcDriver/tests/ShaderDiskCache.cpp
PR 6235	core/libs/prx/libSceAgcDriver/tests/ShaderDiskCache.cpp
PR 6280	core/libs/prx/libSceAgcDriver/tests/ShaderDiskCache.cpp core/shader/recompiler/ShaderDiskCache.cpp
PR 6412	core/libs/prx/libSceAgcDriver/tests/ShaderDiskCache.cpp core/shader/recompiler/ShaderDiskCache.cpp
PR 6488	core/libs/prx/libSceAgcDriver/tests/ShaderDiskCache.cpp core/shader/recompiler/ShaderDiskCache.cpp
PR 6539	core/libs/prx/libSceAgcDriver/tests/ShaderDiskCache.cpp core/shader/recompiler/ShaderDiskCache.cpp
PR 6788	docs/user/USAGE.md
PR 6879	core/shader/recompiler/ShaderDiskCache.cpp
PR 6924	core/libs/prx/libSceAgcDriver/tests/ShaderDiskCache.cpp core/shader/recompiler/ShaderDiskCache.cpp docs/user/USAGE.md
PR 6946	core/libs/prx/libSceAgcDriver/tests/ShaderDiskCache.cpp core/shader/recompiler/ShaderDiskCache.cpp docs/user/USAGE.md
PR 6947	core/libs/prx/libSceAgcDriver/tests/ShaderDiskCache.cpp core/shader/recompiler/ShaderDiskCache.cpp docs/user/USAGE.md
PR 6970	core/libs/prx/libSceAgcDriver/tests/ShaderDiskCache.cpp core/shader/recompiler/ShaderDiskCache.cpp
PR 6977	core/shader/recompiler/ShaderDiskCache.cpp
PR 7223	core/libs/prx/libSceAgcDriver/tests/ShaderDiskCache.cpp core/shader/recompiler/ShaderDiskCache.cpp
PR 7332	docs/user/USAGE.md
PR 7395	core/libs/prx/libSceAgcDriver/tests/ShaderDiskCache.cpp core/shader/recompiler/ShaderDiskCache.cpp
PR 7417	docs/user/USAGE.md
PR 7484	core/libs/prx/libSceAgcDriver/tests/ShaderDiskCache.cpp
PR 7550	core/libs/prx/libSceAgcDriver/tests/ShaderDiskCache.cpp core/shader/recompiler/ShaderDiskCache.cpp
PR 7642	core/libs/prx/libSceAgcDriver/tests/ShaderDiskCache.cpp core/shader/recompiler/ShaderDiskCache.cpp docs/user/USAGE.md
PR 7684	core/libs/prx/libSceAgcDriver/tests/ShaderDiskCache.cpp core/shader/recompiler/ShaderDiskCache.cpp
PR 7689	core/shader/recompiler/ShaderDiskCache.cpp
PR 7800	docs/user/USAGE.md

[tibzejoker]

Overlap with #6771 (@XairRrR): that PR moves vk-pipelines-*.bin into the version subdirectory, where the existing one-hour rule already removes temporary files. If #6771 merges, the pipeline cache's own temporaries are covered without this change. What this PR would still do then is remove the files that older builds left in the root. That is a one-off cleanup, and deleting them by hand works just as well.

So: if #6771 is going in, I'm fine closing this one; it may be worth adding the root cleanup there instead. If #6771 stalls, this is the smaller fix for the leak. The USAGE.md line conflicts textually either way. I'll rebase whichever stays open.

Written with AI assistance (Claude Code).